Clean Code – Software development by and for people

At the beginning of a software project, it is about choosing a tech stack, the core set of those technologies that will be used to solve the problem at hand. At the same time, a software architecture must be chosen to determine and ensure the basic organisation, components, relationships with each other and with the environment, and evolution of the intended software solution. Continuous Integration and Delivery must then be configured. And then the real work begins, the programming.

Clean code illustration

Software development is a broad field

A rough distinction is made between software development on a „small scale” and “large scale”. In training or (self-) study, one works with software development on a „small scale”. On your own, you write short code fragments to learn core competencies such as the use of loops and conditions. As soon as you start working on your first practical projects or in your job, you are confronted with software development on a „large scale”. You write more complex code with several people and are embarrassed to have to extend or change your own code as well as code written by other people at a later stage.

git blame
Figure 1: git blame

 

A crucial factor is the readability of the code at hand. It is not only a key factor for success and costs, but also for the work of the developers. They should be able to put all their energy into their work instead of being confronted with frustration, fear of `git blame` and the fixing of inconsistencies. And this is where Clean Code comes into play.

Software development for humans

Programming code is primarily written for machines. Machines are generally much more frugal than humans and are satisfied with semantic correctness. From the machine’s point of view, compiling code, i.e. code that can be interpreted by it, is finished and completely sufficient. Humans, however, are far less frugal. In addition to correct semantics, they also need logical structures and eloquent formulations so that they can process the code coherently.

If programme code is difficult to understand and read, human productivity is lost in the long run. Changes take more time and become more risky because they are only partially comprehensible.

As the project progresses, the creation of new code moves into the background and the modification of existing code becomes the norm. If software developers now read more code than they write, the costs explode in relation to the time spent.

Fast & Dirty vs. Clean Code
Figure 2: Fast & Dirty vs. Clean Code

 

Clean Code helps to resolve this pain point in that:

  • Human productivity is permanently maintained through easy-to-read code.
  • Costs for changes remain manageable.
  • More time is gained to create value.

With small steps to success

Completely independent of the programming language used, there are many small, actually trivial measures that immediately contribute to a better readability of code. Three of these measures are explained below.

Naming-Things

 

Choosing clear names is one of the oldest and most essential problems in computer science. Choosing meaningful names for variables, functions, classes and packages takes more time, but saves it in the end.

Names should be unequivocally and describe the content: The path of least ambiguity is the right one. What is written on it should also be in it. In addition, context is substantially to creating comprehensibility: well-named variables in clearly named functions in eloquently named classes.

Here’s a real-world example from React that was criticised in the code review:

 

const [currentSelection, setCurrentSelection] = useState('')

From the context of the class it could be deduced that it probably had to be about the selection of users who should get access to the element. The quick and easy improvement of readability could be achieved as follows:

const [currentUserSelection, setCurrentUserSelection] = useState('')

Comments

Robert “Uncle Bob” Martin, co-developer of the Agile Manifesto and grandmaster of the Clean Code philosophy, sees the use of appropriate comments as an attempt by developers to compensate for their own inability to express themselves clearly in code. He believes that before writing a comment, time and energy should be invested in revising the code for unambiguousness. He also argues that comments are often not maintained and thus there is a risk that a comment not only does not help to understand the code, but can even spread misinformation.

Nevertheless, he also lists good types of comments, such as ‚to dos‘ or even public documentation in APIs.

My personal experience shows that the truth, as so often, lies in the golden mean. Especially when you are in the realm of legacy maintenance, clarifying comments are vital and even if the knowledge levels of technological specifics are (still) present in the team, they can be appropriate.

Here is a (particularly) bad example:

// the day of the month
number dayOfTheMonth

The naming of the variable is already sufficiently meaningful. The single superfluous comment is in principle irreleveant. However, if we view it in the context of a large business object, such as personal data management, the code can quickly become twice as long and thus confusing without gaining in meaningfulness through the comments.

Here is a positive example:

/* TODO becomes obsolete with the completion of ticket xy and can then be removed */

Formatting

The main task of professional software developers is communication and formatting, i.e. the presentation and structuring of code in files, is an essential form of communication that allows conclusions to be drawn about the general care and attention to detail throughout the project.

Every modern integrated development environment (IDE) provides automated code formatting tools that should be used consistently by the team.

Here is a poor and confusing example of a while loop:

while (i<10) {text+="The number is "+i; i++;}

With clean formatting, the loop becomes readable:

while (i < 10) {
text += "The number is " + i;
i++;
}

Wrap-Up

Software development is not only 0 and 1, it is risky, takes time and money. One of the many means of controlling risk and thus costs in software projects is Clean Code. Even with simple measures, success can be achieved in new and further development through readable code.

The measures listed here are only the tip of the iceberg. To become a Clean Coder according to Uncle Bob’s ideas and to come back to code written in the past with less frustration, his books are a perfect start.

 

Sources

  • https://martinfowler.com/bliki/TwoHardThings.html (retrieved 13 September 2021)
  • Martin, R. C. (2009). Clean Code: Refactoring, patterns, testing, and techniques for clean code ; [comments, formatting, structuring ; error handling and unit testing ; numerous case studies, best practices, heuristics, and code smells]. Germany: mitp.
  • https://www.q-dan.de/ (retrieved 13 September 2021).

 

This article was originally posted by frobese GmbH – read the original article here!