What is the best software code

Better code with five tips

The Code Codex: A etiquette for good code?

Good code or bad code - there are many definitions of how code quality can be identified. However, the readability of code is often an important criterion. Which golden rules should developers adhere to in order not to make life more difficult for their colleagues than necessary?

Nobody likes to read or work with bad code. It's exhausting, it's annoying, and it costs time that could actually be used for something else - even if it's just the next YouTube video. Trying hour after hour to untangle other programmers' bad code is just not nice at all, as most developers agree. In this respect, one can argue with Kant that good code is a good thing:

"Act only according to the maxim by which you can at the same time want it to become a general law."

In other words, don't write bad code if you don't want to read bad code yourself. Then there is more time for the YouTube video in between - which you don't need so badly if your nerves are no longer strained by bad code. But what exactly is good code?

The Code Codex

There are many code labels and coding guidelines on the web and even more advice on what really good code should look like. Sometimes these compilations are reminiscent of the much-invoked netiquette. Most of us do not need this set of rules - and those who do not adhere to these basic rules of coexistence are not interested in netiquette either.

Ultimately, however, everyone has their weaknesses and may not be so sure what a good coding style would be. Some things just creep into everyday work, other ideas may come from a specific situation in which they were good and right, but they are no longer today. So comparing your own style with a few overarching ideas of good code can't hurt, right?

1. Comment on code well

The first rule of the Code Codex is so banal that it could actually be summed up in one sentence: Good code contains good comments! And that's the end of the issue, isn't it? Unfortunately, it's not that simple. The question of the correct comment rate often creates uncertainty, especially among young professionals.

Basically, code should be understandable in and of itself. Comments can also be designed so that people who cannot program understand the code. But this is usually not particularly useful. If the manager needs to be able to understand the code without programming experience, DSL should be used rather than countless comments in the Java code. Comments are useful where code cannot be designed in a way that other developers can understand immediately. Even when it comes to documenting the purpose behind a function, a comment is worthwhile - the “why?” Cannot always be included in the function name or in the code.

More comments are usually only necessary when working with assembly language. Nobody can read this, so everything needs to be explained. Completely commented code sections with a comment on every line of code are otherwise a relic from the (American) universities, as John Fuex says. There they serve to acquire new skills. In everyday working life, however, one can assume that the general functionality of the programming languages ​​used in the project is known to all those involved. Recourse to the academic principle may only be worthwhile when new libraries or languages ​​are used.

2. Header comments?

Long header areas above the code with a lot of information are no longer very popular. Version histories, author information and the like should only be noted there if no version control is used. Git and the like record this information automatically and more clearly than the individual files of the project. There, the information can usually be found anyway due to the number of lines outside the field of view and can therefore only be used with a lot of scrolling work.

Once such a header exists, however, many developers feel obliged to follow the tradition of their predecessors on the project and spend an unnecessarily large amount of time doing this additional documentation. The only exception are projects whose comments are automatically read out and transferred to documentation. Here, too, the version history does not always have to be recorded; however, it can be useful to collect information about the tools and language versions used in this way.

3. Find the right names

But how do you convey what code does without simply writing it in a comment or header? To do this, you need good names in the code: The names should express what the code does without degenerating into half a comment. Short, concise formulas and clear expressions should be found - and if that is not possible, the code may need to be reconsidered. If you can't express exactly what your code is doing, you may not have found the best solution. In addition, names should consistently follow a scheme: Whether CamelCase or prefix naturally also depends on the language selected. However, where developers have a choice, they should decide on a form of naming.

In every programming language there are of course also allowed and not allowed names for classes, functions and Co. Anyone who simply defines a name without paying attention to these rules has to end up debugging too much. You should also pay attention to clarity. Abbreviations in names are not a good idea unless they are generally accepted standard expressions. Anyone who introduces their own abbreviations can be sure that their colleagues will have problems with them - so the name must not be too short. However, names that are too long are not good either. The name should not contain any information already expressed by the code. So it should describe what the code does and not (just) name how it does it.

4. Observe community and language standards

Apple has published (among other things) guidelines for working with Objective-C in general and the Cocoa API in particular; There are several coding conventions for PHP. There are also some suggestions for Java about what good code should look like. Of course, similar standards and recommendations also exist for other languages! And every developer should know this for his preferred programming languages. Nothing works without it.

This variety of conventions and rules also means that there cannot be a single code of good code. Some things, like not adding too many comments, are certainly applicable to many languages. However, other conventions can be very different from one another. In this respect, developers should always keep in mind that you don't necessarily make yourself popular by disregarding traditional conventions. Your colleagues certainly know the conventions of the project's language too. The project standards are of course an important exception. However, if a project follows its own conventions, these must be well documented - otherwise the code will be difficult to understand for colleagues who will take over later.

5. Write documentation

The agile manifesto suggests, however, that one should develop good, understandable software instead of forever documenting everything that was not solved so well. So why is documentation now part of the code codex? Very simple: It depends on what is documented and how you do it. Even the authors of the agile manifesto probably didn't have in mind that nothing should be documented anymore. In the end, the user should get by without extensive documentation - for colleagues who may have to maintain the code for years, however, documentation is really helpful.

This applies to your own conventions and naming styles; But this also applies to access to your own APIs and the general structure of the project. Good documentation can mean the difference between problem-free long-term maintainability and the great frustration of colleagues. Good comments in the code are an important part of the documentation. Nobody wants to have to read long before they know what a function does. The overall picture, including problems that are still open and implementations that have not been optimally solved, should definitely be recorded in a separate documentation to enable a quick start.

... and a lot more

Of course, every developer and every team has their own code codex. This includes, among other things, that no bugs are simply left in the code without saying something; this includes meaningful and stringent indentation of the code and the limitation of the line length. Of course, regular code reviews are also part of the Code Codex: Four eyes see more than two, so a review helps to increase the quality of the code. It is also controversial whether cute dinosaurs belong in the code. And then there are individual factors that differ from project to project and developer and developer. With the five tips mentioned above, however, you can avoid some mistakes that can lead to bad code!

What is the most important code codex for you? Let us know via the comment function!

Reading tip: Etiquette for software architects - Reloaded

If you want to learn more about software developer etiquette, we recommend the “Etiquette for Software Architects - Reloaded” from developer.press. The authors Peter Hruschka and Gernot Starke will show you entertaining and practical ways to better software architectures - effective, timeless and technology-neutral! You will find typical software architect behavior patterns, good and bad. Success patterns will teach you how to build better systems and work more effectively. From the "anti-patterns" you can derive remedies against bad architectural manners. Particular attention is paid to the evolution and change of systems.

Lead picture: Max and Moritz (Busch) 040.png (Public Domain)

Our editorial team recommends: