Good Housekeeping

Clean code is a set of rules and procedures that make it easier to read and understand source code regardless of the programming language used. Many clean code strategies fit all languages, but some more far-reaching strategies only prove useful in the object-oriented world. The clean code concept is not new or revolutionary. Back in 2008, Robert C. Martin described the procedures in his book, Clean Code: A Handbook of Agile Software Craftsmanship [1].

With today's highly complex IT applications, ensuring that source code has a clean structure has becoming increasingly important. The clean code concept has evolved in recent years, and the procedures described in Martin's book have been expanded. To get you started writing cleaner code, I'll describe some of the core ideas and rules of clean code.

The Scout's Rule

"Always leave code cleaner than you found it." If you take this rule to heart, a project's source code will get better and better over time. You don't need to be afraid of breaking something, because the previous version can always be restored thanks to the version management (i.e., Git). Modern IDEs also provide many tools for reengineering code. Renaming classes or methods doesn't pose so much of a risk anymore.

Typically, the compiler doesn't care what names you assign the individual program components. Whether you use uppercase as opposed to lowercase or underscore instead of CamelCase, as long as the name fits together somehow, the compiler will build an executable program.

However, this freestyle kind of code can be extremely difficult to read. Instead, you should to stick to the style conventions that apply to the programming language being used. In Java, for example, class names should always start with an uppercase letter, while methods should start with a lowercase letter. Modern IDEs usually have a feature to automatically format source code: You should definitely use this. If several people are working on a project, they need to agree on using the same format.

Mnemonic Names

A program's components should always be given mnemonic names. This rule applies to classes, methods or functions, and variables. The names should not be too long, but they still should describe precisely what is happening.

You also need to keep in mind the variables' validity range. It is perfectly fine to follow conventions when naming the loop variables, as in, i or j. And x, y, and z are certainly the most meaningful labels for a coordinate system. But if a variable or object is used in a larger context, you should definitely give some thought to the name.

Avoid including the class name in the method names. All programmers should understand that a method always works on the object in which the method is defined. While you should always use nouns as class names because they represent entities, method names should include verbs. Ideally, avoid using abbreviations in the names; there are some exceptions to this (e.g., VAT).

While it may sound peculiar at first, make sure the names you choose are pronounceable. People will need to talk about a class in meetings or code reviews. Not having overly complex or similar sounding names will make talking about a class easier.

As a universal rule, a comment should never be necessary to explain a component's purpose. Instead, the name should speak for itself. In other words, do not use meaningless generic names such as manager, helper, handler, processor, and so on. A class is always intended for a specific purpose, so name the class for that purpose. For customer projects, make sure you use the customer's designations for the names; otherwise, misunderstandings will repeatedly occur.

Choose names to show the idea, responsibility, and limits. For instance, if you use the Model-View-Controller architectural pattern (which subdivides software into the data model, view, and program control components), then name the classes Model, View, and Controller. Additionally, include the concrete function in the name (e.g., LoginController or ContractSaveController)

Type names do not belong in method and variable names. Instead of writing

List customerList = getCustomerList

use

List customers = getCustomers

You can already tell from the type that it is a list. In addition, you should always use the same name for an entity (such as Login, User, or Account). Filler words such as to, from, and the like should be avoided.

Comments

"If the compiler understands the code, so must the developer." This rule means that comments are unnecessary. This statement, which seems somewhat short-sighted at first glance, makes perfect sense in a slightly modified form in the clean code context. If you feel the need to add a comment to a program section, you should think again about whether the code is really clean. The same applies to the names of classes, methods, and variables.

I'm not saying you can't include comments in your code anymore. Instead, comments should prompt programmers to consider rewriting a code passage in a more easily understandable way. A comment needs to describe what the developer was thinking or trying to accomplish when writing it.

On the other hand, to-do comments are allowed, assuming that somebody actually does the work. The developer can use a to-do comment while still working on the code. Strictly speaking, however, a to-do comment should never make it into the repository. If it does, it must include a specific target date for completion.

Tools such as Javadoc can be extremely useful in many cases. You can automatically generate the necessary documentation, more or less as a side effect of using the tool. However, this automatically generated documentation is only useful as long as the comments in the source code are up to date. Pay special attention to this: Almost all developers rely on up-to-date documentation.

Variables

Always define variables just before using them in the program code. This approach offers several advantages:

• The program code and the matching variable definition fit on one screen page and can be read together.
• The variables' scope is clearly defined. Writing all of the variables at the beginning of a program is by far one of the worst ideas, because it would make all the variables global.
• Variables and objects take up memory and should therefore only be defined when they are actually needed (something that many developers no longer consider).

In the end, unclean code needs more system resources. This results in users needing more hardware, which in turn requires more power and pollutes the environment. Saving physical resources is obviously easier than saving virtual ones.

Methods

When it comes to using methods or functions, you can do a number of things to improve your code. Always choose meaningful names for the transfer parameters and the return values. If the IDE generates these names automatically, make sure you rename them to reflect the actual function.

Methods should only do one task at a time, but they should do it completely. Try to get into the habit of always using the same order for the methods in a class (e.g., the constructor first, then the public methods, and then the private methods).

Methods and functions will ideally contain no more than seven statements. If a method becomes longer, think seriously about breaking it down into several smaller ones. It is also useful to remove complex logical expressions from the if command and move them to a private method.

Methods operating on private variables should either set a value or return one (get or set), but not both. Do not use flags to change the way methods work. Instead, write two methods rather than including special versions of a method.

Methods should not have too many parameters. If you end up with four or more parameters, you need to consider whether it would make more sense to split up the method. Another possible solution is the use of parameter objects. Methods should not modify the transfered parameters or objects if possible. It is cleaner to create new objects and return them.

More Tips

You can employ side effects when programming code so that one command performs several tasks at the same time. This practical approach makes the code very short and compact. However, this approach can pose risks, because not every developer can easily recognize these side effects in the code. Try to write simple and understandable programs rather than "clever" ones.

Another option, the To approach, is a top-down process where you break down a task into increasingly smaller sub-steps. In the end, the individual steps consist of simple, short methods. You can also start by first writing comments to describe what you want to happen, and then implement the methods themselves. In the To approach, a method's results are passed to the next method.

A class corresponds to an entity and must describe the entity completely. Try to create as few classes as possible. When doing this, keep classes as small as possible, and handle only one task per class where practical. Coupling of classes needs to be as loose as possible. This makes it much easier to replace a single class.

All good programmers are proud when they create a working loop for the first time. Unfortunately, this leads to the habit of using Magic Numbers, which are numbers that appear in the code without any comments and control some loop or specify a limit value in a condition. These numbers have no real meaning for the reader, but the code does what it is supposed to do in a magical way. You should replace these numbers with constants using mnemonic names, which will result in more readable code.

When you start developing the source code, don't optimize for speed first. Instead, work on making the code readable. If it turns out that program execution is too slow, you can always optimize the offending code passages.

And always be aware that you may be prone to forgetfulness yourself. The rules and tips mentioned here are intended to generally build source code in a way that makes it easier to understand. It's not only others that will benefit from this, but almost certainly your future self as well. Nothing is more annoying than not understanding your own code after a few months.

Being Professional

I only covered a few of the aspects that are important for creating clean source code. If you'd like to learn more, check out Martin's book, Clean Code [1], for invaluable information.

Even though software is often created with the help of tools, these tools have only a minor influence on the product's quality. The developer, on the other hand, bears the larger responsibility of delivering quality software. For that reason, it is extremely important for the developer to work efficiently and cleanly. Another book by Martin, Clean Coder, provides great insights into the developer's daily grind [2]. The book describes the typical problems in software projects and shows ways to solve them. You not only need to know how to create clean code, but also how to become a developer with a clean work approach.

Conclusions

Building programs using the clean code approach is more of a marathon than a sprint. You can't implement all these tips and rules overnight and write only clean programs. However, to paraphrase the scout rule, it is possible to program a little better every day. The advantages are obvious: Easily understandable code is easier to use and maintain. On top of that, it's also much more fun to work with clean code. Even when pottering with Raspberry Pi projects, clean code can make your life easier, so start today!