Principles of Maintainable Code

The best programmers in the industry love to call themselves “lazy programmers.” This doesn’t mean that they don’t like to work, quite the contrary. Although most of these developers love writing code, they hate writing the same things twice, rewriting what others have perfected, going back into code all the time to fix yet another issue and having to manually do things that should be automated. These developers are constantly implementing the principles of maintainable code.

Throughout all of the maintainability tips appearing in this book, there are several themes that will often recur and form the basis of the principles of maintainable code. All of the maintainability tips are designed to attain one or more of the following principles.

Principle 1: Understand that maintainable code is cheaper to write, debug and extend.

When considering how much a software system costs a company, we have to consider more than the cost of developing or acquiring the software itself. In addition to licensing costs, there are labor costs for developers, quality assurance personnel, database administrators, network administrators and so on. Whoever is involved with a system increases the cost of that system. Even if an employee is not dedicated to a product, the two hours per week they spend restarting the system are two hours not available to other tasks in the company.

In addition, the cost of a software system includes the cost of damages associated with that software system. If the company has to reimburse customers for a missing item from an order, the cost might be relatively small. However, in the case of a malfunctioning insurance system the cost of damages could be much higher if a policy is printed incorrectly and litigation results from the mistake.

When we try to improve the maintainability of code we are trying to reduce the cost of the code and limit the number of business errors caused by the code. When we reduce the damages caused by the system, the company’s reputation improves along with the quality of their products. When we reduce the operating costs of a software system, we allow those database and network administrators to do something other than nurse the system along. In addition, the business benefits from maintainability through lower hiring and training costs. Finally, when we improve the codebase to reduce the cost of adding new features, our companies are better able to react to changes in their business model.

Principle 2: Designing code to push errors up in the development process allows those errors to be discovered quicker and repaired faster.

When a customer reports an error on a system, the error report is often not very helpful at all. Typically a customer will tell you, for example, that they ordered one kind of product and got another or that they were double charged for a product. These errors could be anywhere in the codebase. Locating one of these errors requires the developers to try to replicate the bug, which could take an indeterminate amount of time. After the bug is reproduced, the next step will be for the developers to trace through the code to diagnose the issue. The long process makes the cost of that particular issue very high.

By contrast, an issue that throws a particular exception or reports an obvious error will be much easier to find. The developer will be presented with information that accelerates the diagnosis phase and thus makes the relative cost of the issue much less.

When the quality assurance (QA) department catches an issue using an automated test, it costs even less than an issue that makes it through to the production environment. First of all, when the issue is fixed, the software does not have to be released again to the customer, which can be costly. When it comes to locating the issue, since the QA department already has a test to replicate the issue, that part of the debugging process is already complete. Furthermore, since a professional QA engineer detected the problem, it is more likely that the developer will get better information for diagnosing the problem than he would get from a customer. Naturally if the QA test produces a stack trace or error log, the debugging process is even easier.

When an error is detected by a unit or integration test written by the actual developer writing the code under test, the debugging process is even cheaper because the developer is intimately familiar with the code that they are testing and can quickly repair any issue that the test detects. When a developer is trying to repair an error detected by another developer’s test, the cost is slightly higher than the single developer scenario, but still the intercommunication of the developers usually makes the cost cheaper than a defect detected by QA.

The cheapest defect is one that is detected by the compiler when the developer is writing the code. Developers are prone to correct syntax errors without any more conscious thought than they give to breathing. More complicated or cryptic errors marked by the compiler are only slightly more expensive in terms of hours spent on the problem. A developer might look a little quizzically for a couple minutes at a compiler error but usually they can solve them rapidly. A warning issued by the compiler sometimes takes a bit longer.

Our goal as a developer should be to try to push a defect down in cost by exposing it at a cheaper level thus creating a shorter feedback loop. By adding mechanisms for logging, trapping and exposing errors, we can reduce the cost to maintain the program. By adding automated tests to our software system, we will be able to reduce the cost even further. Finally, if we use language mechanisms that can push an error to the compiler stage, we can prevent issues from even leaving our development machine.

Principle 3: Reducing the amount of code in the system makes code less expensive to maintain.

Although this principle might seem self-evident to many, there are plenty of enormously bloated software systems out in the business world. Over-engineering and re-inventing the wheel are overrunning the battle lines of maintainable code. Furthermore, developers re-inventing the wheel are not likely to produce a result as high quality as that particular wheel produced by dozens of developers and tested by thousands of users. Reducing the size of a codebase means that you have less code to write, debug, build, test, deploy and monitor.

Principle 4: Code that maintains itself lowers maintenance costs.

If you can write code that is flexible so that it maintains itself when requirements change then you will only have to debug the code once and not whenever you make changes. The more manual changes you have to remember, the higher the potential that something will be forgotten, not communicated to new developers in documentation or otherwise missed. Developers would be well advised to use techniques that can automatically adapt to the introduction of new enumeration values, command handlers and so on.

Principle 5: Reducing complexity makes issues easier to find and repair.

Code that has higher complexity is harder to follow when the developer is reading it. This is especially true in the case where a different developer wrote the code. When there is confusion in a codebase about a process or a specific path of logic, the potential for errors is much higher as is the difficulty in developing effective tests. Keeping a codebase simple makes the logic easier to follow and reduces the number of defects in the system.

Principle 6: Reducing the number of technologies in code makes for a smaller necessary skill set.

There are a lot of technologies out there that implement all kinds of frameworks and design patterns. However, when we stack technology on top of technology, we increase the competency requirements for developers that must maintain the system. Although the current developers might be fully versed in all of the relevant technologies, turnover in IT departments is a fact of life. If there are a large number of technologies in a system, replacing personnel can be difficult and expensive. Furthermore, even if your company is willing to compromise on a developer that has many of the skills but not all, the training time before the new developer is productive in the codebase will be much higher. Finally, even after you have the new developer trained, he is still more likely to make errors on a complex codebase consisting of many technologies. The more complex your codebase and the more technologies you introduce, the higher the investment and commitment you must have to your developers because your product will become dependent on their knowledge.

Principle 7: Facilitating the use of a stepping debugger reduces debugging time and improves maintainability.

Stepping debuggers are absolutely the best tool for debugging complex code. There are some developers that still use print statements for all of their debugging but they are doing themselves a disservice. Stepping debuggers have an immense amount of functionality that allows a tester to manipulate data and inspect details in the program. Anything you can do to facilitate the use of a debugger will lower the time it takes to find a problem. Developers that absolutely refuse to learn to use a stepwise debugger will inevitably be significantly less efficient than...