Documentation in code – pros and cons

How important is documenting code? “Very important, of course, because it makes code easier to understand!” – some people say. “Unimportant” – answer others, “because as soon as software developers follow the principles of Clean Code, separate documentation is unnecessary!”. Some also argue with a middle course: “You should document what should not be forgotten!”.

If opinions differ that much, then it is time for pros and cons for documentation of source code.

Why do software developers not like to document code?

The world of programming could be so beautiful if software developers would simply comment on their code. But they do not. At least not all of them, not always or not in a uniform way. There are a number of reasons for it to be so:

• Documenting code is time-consuming. A comment takes time. More time than no comment. And this time is missing for other nice things, like coding.
• Software development often takes place under time pressure, so that comments are often not maintained and as a result the documentation does not match the updated code.
• The documentation has no influence on the performance of an application. Additionally, compilers, interpreters or minifiers will eliminate comment lines.
• In development departments there is no uniform procedure for creating and maintaining comments. The documentation is at the discretion of the individual developer and therefore it is accepted if the developer waives the documentation.
• Documenting is no fun, it is even boring to a certain extent.

In addition, there are also a number of reasons that are often not stated, although they are just as clear as the arguments that are more often mentioned:

• Software developers overestimate themselves. For example, many developers do not lack the insight to implement Clean Code values and principles, but they lack the skills. Thus many focus on the correctness of the code, but at the same time negate its mutability. As a result, they do not see the need to document.
• Software developers overestimate themselves – Part 2. Due to the fact that developers are not able to implement a second or third best solution, but always believe that their lines of code solve the defined task best, they often cannot see that there are actually other, better ways. They are convinced of their implementation. From their point of view it is clear and absolutely logical. Of course, something logical does not need to be documented.
• Software developers misjudge themselves. Many developers believe that documentation should make life easier for other developers. Why should they invest time and effort in this? But they misjudge themselves, because they are often the ones who have to deal with the implementation in six, ten or 12 months, but then no longer know why they have realised what and how.
• Nobody likes to be replaced by another worker. Salespeople don’t, marketing experts don’t and software developers don’t either. Good documentation makes it easier for other developers to work with the code – why would a software developer want that?

Please don’t misunderstand me: some of the reasons mentioned are all too human and therefore not surprising.

Why should software developers document code?

In fact, there are two main reasons why software developers should document code:

• It is extremely difficult to read code. Even if software developers are trained in reading code and use line numbers to quickly navigate between code passages, understanding the syntax used is not easy. By using comments, developers can communicate their intent. The documentation reveals the intention of the code and not its functionality, because that is the result of the code. An aspect that is also important in code reviews.
• The documentation makes it easier for all parties involved to change the code (adapting the software to new requirements) and to continuously improve the code (increasing performance, implementing bugfixes, etc.). The changeability of code is practically impossible for customers and users to check, but since the implementation of new requirements is daily business in software development, developers should make their own work – and that of other developers – easier.¹

There are several other reasons, such as

• the declaration of complex code areas,
• respect for other developers,
• the concern about the turnover of software developers in connection with the loss of insider knowledge,
• the fear of making mistakes in understanding lines of code,
• or increasing production efficiency².

All in all, however, these reasons must be rated rather subordinately.

What should actually be documented?

Indeed, the question “What should actually be documented?” is of central importance when considering the pros and cons of programming documentation. In some articles on so-called inline source documentation it is propagated to insert comments into the source code that briefly explain individual steps so that other developers can easily understand why a code snippet exists and what its function is without extensive analysis.³ In other words, developers should shoot at sparrows with cannons for safety.

In fact, it makes sense – regardless of whether you are on the side of Pro or the side of Contra – not to do exactly that. Comments that describe how code works and achieves its goals are actually only a second version of the code. And as a second version, they either conform to the code and provide no added value, or they do not conform and provide incomplete or even incorrect information.⁴ Apart from the fact that it is practically impossible – and certainly neither efficient nor effective – to document code accurately and completely, code continues to evolve. Such further development would have to be reflected accordingly in the documentation of the code, and here at the latest, theory and practice run in different directions.

These considerations lead us back to the question: What should actually be documented? And the answer to this question is:

• Comments should explain the “why” of the code. The intention of the developer. And possibly the purpose that a class or a method fulfils, for example.
• In addition, a comment could also explain how the inputs and outputs of a method are related and what “side effects” (e.g. the deletion of a data set) are to be expected.⁵

That is already it. More documentation should not really be necessary.

Conclusion

There are valid arguments in favour and against documentation in the code. Documentation costs time and saves time. It costs the developer time when writing, it saves time when understanding the code at a later stage. Even if the effort of writing is usually many times less than the effort of understanding (especially if it is multiplied by the number of developers who together try to understand the lines of code of another developer), simply demanding “more” documentation is too general and does little to achieve. It is unnecessary to describe in words what is obviously and already clearly formulated as code.

It is helpful to document aspects worth mentioning, especially the intention of the developer when coding and information that cannot be read directly from the code. Ideally, the code itself is clearly structured, follows a logical flow and is both efficient and effective. And it is precisely in this sense that comments should increase the readability of the code: in clear words and with useful but not redundant information, efficiently and effectively.

The discussion about documentation in code is not new and there is probably only one way to end it permanently: Information must be provided in such a way that the implemented code can be understood relatively quickly at any given, later date. This is the goal of documentation. This is a golden rule for software development.⁶ And this is the reason for comments in the source code.

Notes:

[1] The Clean Code Developer School: Putting the requirements on their feet (in German)
[2] Production efficiency aims to make the entire software development process as efficient as possible as part of an application lifecycle management. The longer a software is developed, the more extensive a software becomes, the more important production efficiency becomes. If it is open source software, production efficiency is also important.
[3] DEV-Insider: Overview of documentation types (in German)
[4] Brian W. Kernighan and P. J. Plauger: The Elements of Programming Style
[5] Visual Studio Magazine: Why You Shouldn’t Comment (or Document) Code
[6] A golden rule of software development says: Source code should be written the way a developer would like another developer to write it.

Michael Schenkel has published additional posts in the t2informatik Blog, including

What does t2informatik actually do? One click and you'll know.