The gray line — Comments and Clean Code

Part 1

These few paragraphs have the intention of addressing a topic usually forgotten or despised but with side-back values and damages: The code comments.

The name refers to the usual color of the line of comments, but more than that, to the line between those who are deterministic on both sides. From self-explanatory code to the literates passing through all the greys in the middle where we are supposed to move.

It’s often assumed that every proficient developer recognizes the importance of thorough documentation, but that is in part incorrect and, in a way, inaccurate because even for those who believe that good documentation is needed, it relies on their subjectivity and understanding of what that means.

My goal was to provide different points of view I gathered over time and open the discussion in the company where I used to work but to start with a common ground to set a few rules about comments, documentation, and clean code. Now I just want to share this compilation.

The unbearable lightness of words

Anyone who has ever learned a programming language has heard, perhaps as a first good practice in software development, about well-documented code, and that, in the lack of other better support, is usually reflected in comments in the source code.

Perhaps, later on in your professional development, you have also heard the phrase good code is self-explanatory, or fancier, the self-documented code. It is clear that if there is a code of such quality that there is no place to doubt it, anyone would want to reach that point, and maybe we spent countless hours refining our code to enhance its clarity and design, for sure, without comments. It does not need those.

Whether in our early days as developers, when we wrote extensive comments, or when we applied all our knowledge to develop a masterpiece that WILL BE understood, at first sight, we always did it to improve the quality of our code.

This document has the same goal, improve our code, but the thing is that the words are not as determinants as a computer command.

Everyone understands what quality means. Anyone could think that a product that broke after the very first use is not a quality product… until we read the legend disposable. The same thing applies to the previous paragraph:

• What should we consider as a well-documented code?
• What is self-explanatory?
• What is quality code?

Here lies the gray in between and what we need to solve.

Comments types

We can identify two types of comments. First, the Documentation Comments, are intended for the users of our code, but there’s no need to dig through it.

Examples of this type of comment could be the explanation in a public function of an SDK, or those used as input for the automated generator, like JavaDoc and PHPDoc, among others.

Of course, it is a simplistic example, but you get it. I don’t want to debate the value of this comment (yet), but just about understanding the type of it.

Is a function description, using some standard to make it eligible to be used by an automated tool and provide some information to the person who will use the piece of code. No information is too much or will harm us, right? (Spoiler alert. Yes, it does).

Some of these automated tools are powerful, and it makes a lot of sense, but we will get there in a bit.

The other type of comment is the Clarification Comment. These comments are for those who actually read, refactor, extend, and/or improve the code. Here is a great (bad example) of clarification code:

Or maybe this:

You can read a lot of this here, and feel free to make your own; I am pretty sure that we all have one or two (probably more) examples of this, even though I am not sure if we had a real-life example, non-debatable, about clarification code.

I want to separate this type of comment not for itself, but for the objective audience. It is more likely that someone would look for API documentation rather than the code, even if they listen to the detractor’s phrase “Code does not lie, comments usually do”. So, at first sight, documentation comments probably are more relevant than clarification.

The dilemma: What, Where and How

As we saw earlier, the real problem doesn’t lie in the intention because we want to write better and more reliable code. The real problem hereabouts is what it is, and how to do it.

My approach is a bundle of different ideas I came up it and some of my experiences.

What should be documented?

In her essay Literate Programming, Donald Knuth comes to us with the proposal of a completely different way of programming. I am opposed to that system, but I found some truth there. He said:

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

I agree with this in a manner that this kind of thinking will lead to a better and more understandable code. It probably points out the design, not to the comments itself.

If we design a better code, make the right abstractions, and during that process, we keep in mind that the machine will understand any badly designed and badly styled source code, but people won’t, then we will write better code without the need for a single line of comment, right? Easy peasy.

But he also said:

If we express a program as a web of ideas, we can emphasize its structural properties in a natural and satisfying way.

This makes me ponder. Frequently, the software is not presented in that manner. It usually does the opposite.

Code is a series of structures that try to model a problem, and their interactions will solve that problem. I’m okay with that because we are expressing the solution, but are we aware that we are ONLY doing that?

I’m not sure where I heard it, but I think it’s absolutely right.

Everything might work perfectly and still do the wrong thing.

Code could be as self-explanatory as possible, but even so, it lacks of context of the business problem or the knowledge of the reason behind WHY was written in that way and not in another.

For me (also for Jef Raskin), this is the answer to the WHAT in the comments. We should add context to the problem we are solving, not describe the solution we came to it.

In a simpler way:

Document the WHY. Code the WHAT.

As a closure, I want to give a few examples I came and got me some time ago. The same code in different ways will do the work and make my point in this.

I’m sure we all encounter this kind of comment. Is it meaningful? Does it provide us with new information? Is it more explanatory than the code itself?

Are we accustomed to this kind of comment? Perhaps we have encountered it some time ago, or maybe not, but this one is much more meaningful than the previous one. It provides us with information that we did not have, such as the temperature being expressed in degrees Celsius, how it is set, an edge case, and considerations to keep in mind.

Is this talking about the implementation? YES. Is it bad? It depends on who uses it and how it will be used. If this fragment belongs to an SDK, It is not a good call to add some comments about the implementation, but if in a closed-source project, your teammate probably will love you instead of blame you for this.

One thing it’s important to keep in mind. In the words of Jeff Atwood:

The value of a comment is directly proportional to the distance between the comment and the code

So, given that we are writing a comment with implementation details, we need to update those comments each time we change the implementation, and the further it is from the code which it refers to, the less likely to be updated it is, and with time, becomes irrelevant or wrong. We need to be extremely careful with where and specify which part of the context is relevant at which point or even which media because we are not the only ones who will update our code and comments.

And what about this? It’s a mix of a comment with some context, and the obvious part of the function. Should it be there? Sometimes you need to consider applying the YAGNI approach.

In this exploration of the world of comments and clean code, we’ve thrown some shade at the idea of drowning in extensive code documentation. Dive into Part 2 with me as we unravel the practical ‘How’ of code commenting, addressing pitfalls and advocating for a purpose-driven approach to documentation.