Does the following situation seem familiar? An application that has been working reliably for many years suddenly needs a security update somewhere in the code. It’s the software of all things, whose documentation has been somewhat neglected since the last release(s); the software, whose original developers are no longer available. So, what do you do?
…You grab the best software developer you can find and set him up for the necessary update. However, this person has never seen the source code. What do you think the cost will be? Just count the developer’s swear word – every single one of them is an indicator of the amount of costs involved.
Not amused? I can imagine. In this article you will learn how the principle of clean code can help save you from this scenario.
Why developers scold programming
First of all, I will explain why developers complain when they see ‘bad’ code and why it increases the effort they have to put in. Imagine moving to a colleague's office four times a year. You have half an hour maximum to remove contaminated sites, move the furniture and sort all the documents. What do you want? Right, that you are given a workplace as tidy as possible! The same applies to software developers when they take over a source code that is new to them. If they have little time, they are running the risk of not only dragging the chaos of his predecessor along but possibly aggravating it further.
What is the solution? A tidy code! Software developers refer to this as clean programming or clean code.
What is ‘bad’ code and how does it come about?
In long-term projects with changing developers, ‘bad’ code always arises when the planned budget is too low for quality measures or refactoring, and the time to release is tight. In such cases the developers only make sure to implement the requirements placed on them and, in the best case, secure them with unit tests. Bug fixes and updates may still be added after the release, but then the whole thing will continue with the next release or even with another project. Good developers therefore rightly demand a redesign or refactoring, because they can only work poorly on an untidy construction site and the effort for the next release increases. Source code that is not maintained according to the principles of clean code is therefore considered ‘bad’ code.
There are anti-patterns that lead to bad code and that we absolutely want to avoid in modern software. Clean code not only describes how the source code should be structured; functions and architecture can also be designed clean.
Write your code as if the guy who needs to understand it is a psychopath with an axe who knows where you live.
Clean software is worth more
The use of business software mostly has economic reasons, since it is a critical success factor in many cases. Accordingly, it should be well cared for. Depending on the duration of use and the economic criticality of the application, you should plan a development budget big enough for clean code.
The truth is in the source code
Software developers are authors. When you write something, you want it to be read. You’re lucky! With source code, this is inevitably the case. If we want to implement an existing application, we first have to familiarize ourselves with it. Missing documentation and tests further complicate the effort. However, if there are documentation and suitable test cases, the actual familiarization process has just begun when we search the source code and can compile or start the application ourselves for the first time. So, we first get an overview and look for the place where the implementation should take place. For this process, we need to read and understand many lines of source code. It is said that the ratio between read and written code is 1:10;
If the clean code principle is not followed, the effort to understand these 100 lines is enormous and the risk of destroying existing functionality is high. Such code is simply not maintainable – this is the point at which we developers begin to protest.
Produce readable code
Anyone who adheres to the principles of clean code tries to write easily readable source code. This means code that documents itself and can be quickly understood by another developer. With clean code, we create maintainable software that can be read by completely different people even after many years. Maintainable software reduces the risk and is therefore a critical criterion for success.
As so often, the best way to learn is through your own pain. In order to want to write readable code at all, most of us had previously had bad experiences with unreadable code – certainly with our own, where weeks later you no longer know why you initially thought it was brilliant. All that has remained is a thicket of source code – opaque, confusing, and puzzling. Every change suddenly crashes the program and you have no idea how the module could ever work.
Clean code from the start
If you start with clean code, you can use this old scout rule as a model: "Always leave the fireplace cleaner than you found it". This means: If you have read and changed the source code, clean up before you go! A small bonus: Refactoring also helps you understand!
In addition to this rule, the following also applies to clean programming: “Do no harm”. This means that with every implemented change you should know whether the functionality and structure of the application will still remain intact afterwards. Test them! Incidentally, if an application is difficult to test, this is an indicator of unclean design – in such cases, often only that which needs to be changed is changed, as there is no time for major refactoring. This is a fundamental reason why most software projects become unpredictable over time and face increasing costs. For this reason, the following applies to clean code: Testing is important. Only those who test can program properly. It is best to write our tests BEFORE the actual programming. What should the software be able to do when it is finished?
Overview of clean coding
One of the most important rules in clean code is the naming issue. Everything is named in the source code: files, modules, classes, methods, functions and variables. Nowadays it is no longer necessary to keep such terms short because we have enough RAM and monitor space available. The development environment supports changing names; always choose meaningful and unmistakable names which describe the purpose, avoid misinformation, which are pronounceable and have a professional or technical context. Word games, generics, and hidden mental contexts are taboo!
Functions should do the job and be small. There is one level of abstraction per function. You have to be able to tell from the name what exactly is being done. Instead of commenting, a function can be divided into several steps and be given descriptive names. Comments are not redressing for bad code, but they often show areas that need urgent revision. Legal, informational and clarifying comments are still fine, as are declarations of intent, warnings and to-dos.
The biggest discussion among developers is code formatting. The team should definitely agree on a code style, or find a way where everyone can work in their own style without disturbing others. Moreover, clean code deals with further concepts for objects, classes, error handling, but also clean techniques for concurrency and testing, which go beyond the scope of this article.
Even though learning and adhering to these principles is rather time-consuming in the beginning, every developer does themselves, their team, and the software project a big favor with it. If you don't have the time to deal with this, the following quote may help you as a guide: "Write your code as if the guy who needs to understand it is a psychopath with an axe who knows where you live."
If you still need some help with clean coding, please feel free to schedule a meeting with us:
