Synopsis: Diplomatic Immunity

One of my earliest jobs gave me a lesson in the importance of using the best practices of software engineering after a tragic accident left me responsible for an important database application.

I interviewed for a contract job at Hewlett-Packard to develop and maintain an application on UNIX, written in C with HP ALLBASE/SQL. The manager and staff interviewing me told me sadly that their programmer who had worked on that application had had to leave for unavoidable reasons. No one else in their department knew how to use UNIX or anything about the application.

After I started the job, I found that the developer had never written documentation or tests for the application, and that they had never used a source code control system or even code comments. All their code resided in a single directory, including code that was part of the live system, code that was under development, and code that was no longer used.

This project had high technical debt — a consequence of using shortcuts instead of best practices. Technical debt, a term introduced by Ward Cunningham in his experience report for OOPSLA 1992, causes risk and extra work in a project until we pay it off by refactoring, testing, and documenting.

I worked for six months to organize and document the code for what was really a fairly modest application because I had to spend a lot of my time supporting its users while continuing development.

There was no way I could ask my predecessor to help me get up to speed with the project. The experience really demonstrated the impact of letting technical debt get out of control.

Objective: Employ best practices

Professional programmers strive to use good software engineering habits in their projects, such as the following:

• Keeping application source code under revision control using tools such as Subversion or Git.

• Developing and running automated unit tests or functional tests for applications.

• Writing documentation, specifications, and code comments to record the requirements and implementation strategies of an application.

The time we take to develop software using best practices is in fact time saved because it reduces a lot of needless or repetitive work. Most experienced developers know that sacrificing these practices for the sake of expediency is a recipe for failure.

Legitimate uses of the antipattern

One writes documentation and tests as well as truly ad hoc, such as a one-time test of an API function or an SQL query to answer a user’s question. A good guideline for checking whether some code is really temporary is to delete it immediately after one has used it. If we can’t bring ourselves to do that, it’s probably worth keeping. If it is that, it’s also likely worth storing in source control and writing at least some brief notes about what the code is for and how to use it.