In the Code: Writing code cleanly and elegantly

Ergon-CTO Erich Oswald describes the analogies and differences between good code and German essays in clean German and in clean code.

If you look over the shoulder of a software developer from time to time, you will notice that the step we call “programming” is to a large extent text writing. First and foremost, we address the computer that will interpret this text as code. The code must follow the strict rules imposed by the grammar of the chosen programming language.

Beyond that, however, the computer makes no demands. This can be seen in competitions such as the “International Obfuscated C Code Contest”. This is about formatting and mutilating a small program so that you don’t see what it does when you execute it. (Who would suspect that a program formatted in the form of the letter “Pi” with many sequences of the form “3_1415” prints the number e).

In practice, however, we strive for the opposite and try to formulate the code as comprehensibly and comprehensibly as possible. Professional software development is teamwork and requires that everyone in the team can read, understand and adapt the code.

The correct interpretation of the program by the machine alone is not a yardstick. The less time developers need to learn a piece of code, the faster they can add new features to a program, and the smaller the risk of accidentally adding bugs.

The term “clean code” from the book of the same name by Robert C. Martin has become established in recent years for these efforts. Since then, clean code has become a core topic for the “Software Craftsmanship” movement. It pursues a vision of professional software development that is strongly oriented to the craftsmanship and code of honour of programmers.

However, the idea is not new: As early as 1974, the Unix authors Brian W. Kernighan and P. J. Plauger published a book called “The Elements of Programming Style” for the elegant writing of C programs. The reference to “The Elements of Style”, a manual for good writing of American English (“one of the 100 best and most influential books” according to the New York Times), is quite intentional.

Unfortunately, documentation written by programmers sometimes makes you doubt whether it was really written for human readers. It may come as a surprise, but good software developers should ideally also have skills that have more to do with writing German essays than with mathematics exams.

In language classes, for example, we learn that sentences with many nested subordinate clauses are difficult for the reader to understand and complex. The same applies to code:

We limit the nesting depth of program constructs such as conditions and loops to a few levels. Just as we avoid long sections and lead deserts in articles, we also keep individual functions and methods short and manageable when programming. And just as we structure a text in order to control the flow of the reader’s thoughts, we also organize program functions .

Coherent sections that are in close proximity to each other and relate to each other. The names of the functions and methods assume the role of intertitles. Special tools for static code analysis can help programmers to design the code clearly. They determine metrics such as cyclomatic complexity, method length and LCOM4 (“low cohesion of methods”) and criticize that the code is badly organized and becomes too complex after a certain threshold value. Without a minimum of discipline and empathy in the reader, however, the best tools are useless.

In addition to these analogies between code and normal texts, there are of course many differences. Even the vocabulary and formatting of code are special. It is not so much prose as a strange form of poetry that follows the formal grammar of the programming language instead of the rules of verse and rhyme. Moreover, in the case of code, we never intend to reinforce its impact on the reader with rhetorical figures.

On the contrary, a definition of clean code is that it should contain as few surprises as possible for the reader. A teacher in an essay may tell us that we always use the same word for a term: in code we try to use the same name consistently for the same thing and avoid synonyms.

On the other hand, unnecessary, redundant and repetitive repetitions of identical processes in the program are confusing and are considered maintenance traps. Conspicuous features and outliers are undesirable. The more boring, the better!

The analogies between code and poetry are an example of the central role played by communication in software development. Communication with users, clients, operators, team colleagues and last but not least with the machine is an essential part of daily work, but obeys completely different rules. In the case of program code, the same text even has to serve several different addressees, the people and the machine.

This diversity makes the job exciting and challenging, but can also be frustrating: If the machine understands the code correctly, is the work basically done?

After all, this fulfils the customer’s requirements! Investing more time so that other people understand the code faster and better in the future is therefore quickly regarded as unnecessary waste and “gold-plating”. A complete renouncement is however risky and probably leads to higher error rates and increasing maintenance expenditure. It is the joint task of developers and management to find the right balance.

In this sense: I’ve gotten into programming and then I’m going to write cake code (instead of spaghetticocde) again.

“Many Developers Don’t Write Clean Code Because They Just Can’t”

Jens Schauder is an enthusiastic software developer and convinced “Clean Coder”. As keynote speaker at the DevCamp 2017 on February 8th in Hannover he will talk about possibilities to establish clean code in practice. In an interview with DOAG Online, he spoke about the challenges and ways to improve teamwork.

Jens Schauder is an enthusiastic software developer and convinced “Clean Coder”. As a keynote speaker at DevCamp 2017 on 8 February in Hanover, Germany, he will talk about ways to establish clean code in practice. In an interview with DOAG Online, he spoke about the challenges and ways to improve teamwork.

Mr. Schauder, is clean code even possible in practice?

Absolutely. If you earn money with software development, clean code is indispensable. Otherwise the development costs will rise massively sooner or later, nobody can afford that in the long run. There are only two things to consider: First, “clean” and “clean” are two different things. If you have an extremely clean kitchen, it is still a dirty house for someone who needs a clean room for chip production. It’s the same with code.

If you build an import that once runs productively and is then crushed, the requirements are different than if you write software that has been maintained and developed for decades, or if it fails, people could die. Second, many developers actually earn money by spending time in front of the computer. Of course, it is advantageous if the time in front of the computer increases due to poorly maintainable software.

How do you motivate a whole team to write clean code?

Motivation is usually not the problem. There is B.J. Fogg’s behavioral model, which I find quite revealing. For people to do something, three things have to come together: Ability, motivation and a trigger. If I want developers to write clean code, I have to make sure they are able to do that. I also have to make them want it, and I have to give them a push to do it.

What are the hurdles that companies often face?

In my experience, many developers don’t write clean code because they just can’t. The principles of clean code are simple in themselves, but putting them into practice is difficult. This takes time to learn, only pays for itself after a longer period of time, and the added value will never be on a bill as a euro amount. Therefore, the principles are not adequately challenged and promoted in many companies. And in training, clean code usually does not take place at all.

Money and above all time must be invested in the training of developers. But if you really make it clear to the teams that clean code is valued, and for example bring someone into the team who has a lot of experience in the field and can help the others and coach them, then this usually works quite well.

There are a lot of principles to achieving neat code – do you have a favorite principle?

Definitely: the “Single Responsibility Principle”. If every code artifact (line, method, class, package, jar file) has exactly one task, and I, as a developer, know it, I’ve already achieved a lot and many things result from it.

The problem with finding good names is often that you don’t know what the task is. When you find a ‘HelperUtil’ class, you don’t know what it actually does. The original author usually doesn’t know that either. If you think about it, you often come to the conclusion that there are many different things that can be properly named.