Why does changing a single parameter in an already running software require one student, two PhDs and around six hours of work? And how can we avoid such a waste of resources in software engineering?

The answer is code quality.

The concept of code quality is widely familiar to most software developers, and often first encountered in a beautiful spaghetti bowl. Usually served as “completely self-explanatory” and “nearly bug free” by the botcher, that somehow managed to wiggle out of the project right before you.

Code quality – what the maintainer wants

Let me start by telling you this introductory anecdote did happen some way or another. More than half of that time was spent searching for functions, parameters and build-scripts. Imagine three mad men searching the rubble of Cologne’s city archive for a medieval manuscript, and you should have a good impression.

However, the underlying issue of code quality is the different perspectives of the people working with the code: The desire of the maintainer is to fix a bug or implement a feature with minimal friction. They wish to open the documentation, use it to identify the part they wish to rework, and simply add a few lines of code without side effects. That’s it.

So, naturally, the programmer and the maintainer role differ significantly. This even goes so far, that you, as a programmer, may think of the maintainer as the laziest sloth you have ever seen.

Are there, to your knowledge, people reading the entire source code of a project? Often, it seems they read the documentation of a library only after the library defied their attempts at intuitive use. Code in its pure commented form is almost never self-explanatory, unless it explains its meta structure and offers a clear entry portal into the whole project.

If you wish to learn a little more about the mind of a maintainer, you may enjoy How to write unmaintainable code, which can also be found on GitHub.

​Where the bugs live

So, where did the rest of the team’s time go to fix the parameter?

Unexpected, undesired and undocumented behavior, of course.

In other words, bugs.

For the unburdened, bugs do not simply exist in a program, like arachnids on Klendathu, they surface after time. They are small mistakes hidden deep within the code that may cause a host of symptomatic issues without ever being fixed. Like mold in a wall that has not yet surfaced or is constantly being over painted.

These flaws in the code do not necessarily have to be the fault of the developer or programmer. They can also be caused by things outside their view or reach: They are hidden in third-party libraries, hardware or finer, misunderstood nuances of the problem to be solved. The smaller they are, the more difficult they are to find and isolate.

Some people, I met, believe themselves to be capable of writing bug-free, high-quality code. I believe that code becomes very complex very fast and fully understanding what happens inside your system is ambitious at the very least. Therefore, it is recommended to prepare the code for bugs instead of believing everybody will always write flawless code.

Best practice testing

The tool of choice for achieving optimal code quality is – of course – testing. If the entire code is covered by tests, we may not immediately find what broke, but we may at least know what did not. If you’re not sure how to write good and useful tests, there is lots of decent material online. The Ultimate Guide to Software Testing might be a start.

My understanding of the usage and purpose of tests was greatly enhanced by “Growing Object-Oriented Software, Guided by Tests” by Steve Freeman and Nat Pryce, which is, unfortunately, not freely available.

​Why does code look like this?

At the beginning of this article, I blamed the quality of the code on being written by a botcher, but that is almost never the case. Instead, most software developers appear to be skilled. So how does these fit together?

I believe the main problem is perspective. Working four weeks on a project, gives an intimate knowledge of the project, nobody else will achieve. This, I believe, clouds the judgment of the developer or programmer. For you, it may be clear in which kitchen drawer the forks are placed, but for another person it is not.

Seeing the project through another person’s eyes is difficult at least, if not impossible. Of course, we could all spend hours of time educating ourselves about the expectations and implicit conventions of others. But I suggest the lazy approach, just acquiring a foreign view. This is done by peer review. In the best case your project can now be understood by most people, in the worst case you shifted the responsibility for readability to another person, which is still better than being responsible alone. Nevertheless, chances are high that this will improve the quality of your code.

​How to avoid bugs and improve code quality

Now that we have identified the common problems and their source, let me reiterate the advice given in so many lectures by so many people before me: “Keep flaming long enough, and you may just annoy people in accommodating you.“

1. Write an overview document for your code.
2. Document your code, to help the maintainer navigate it.
3. Write tests that ensure your code works like you intended.
4. Write tests that alarm any future maintainer when they break the code.
5. Have another technically competent person review your code.
6. Implement traps into the code of colleagues who ignore this advice, for their education, and your amusement.

Finally, the best way to demonstrate the value of these rules is to send somebody on a six-hour bug hunt to change a single parameter in poor-quality code. So maybe our colleague just wanted to educate us on code quality.