Code comments are your code autobiography

Originally published at Medium on Jul 25, 2019

Writing about your code is redundant; the code is all you need. I can invest my time on unit tests or develop other features, and other excuses of why writing code comments is a waste of time. It’s a common belief among developers.

Well, you’ve invested all your efforts in cultivating the design of your code, why should you comment it, right? As a result, code documentation is either absent or useless.

Carter Wickstrom

@carterwickstrom

90% of all code comments:

15:14 PM - 03 Jul 2018

While in some cases, it is true that writing code comments can be counterproductive. Yet, we are the only ones who can benefit the most out of it if being done right.

Code comments as a contract

A self-documented code doesn’t exist. You can write meaningful variables names, methods, classes, etc. but as good as it gets, it doesn’t make your code automatically describe the meaning of it.

I Am Devloper - Vote for Pedro

@iamdevloper

"my code is self-documenting" === "I don't work well on teams"

16:28 PM - 13 Feb 2019

Yes, sure during the implementation while sharpening it to perfection, you are in the context of it, but what would happen in a month from now? How much will you remember? Can you trust your future self to be in the same mindset when approaching it?

Realizing what you thought when you wrote this piece of code would assist you in the time ahead. Proper code documentation is making a contract with the maintainer to be, which is probably you.

Code comments are an inherent part of clean code

In some cases, code comments can point on code smells. If you find yourself writing that the method does this “and” that while writing your method’s code documentation. You probably should refactor the method, since it has to do one thing and one thing only. Therefore, break the code into two methods and immediately mend the code comments to fit the change. In such way, you adhere to a clear code concept.

Furthermore, digging into the code to better understand the context of the method is an unnecessary waste of time, while you could easily read the method header and quickly recall the what (_obvious) and _why parts of the method and in particular focus on the how it does what it was written for_._

Take for the example the comment in the below gist, it just states the obvious and tells what it does — basically, it repeats the property’s name, which makes it redundant. While removing it will have the same effect as not writing it in the first place:

A better comment will have more details which state what the code can’t tell us. Well, you can say — why should I write it? The property’s name and logic are straightforward; it just returns weight. But hey, nothing is ever simple in software. A useful comment can save us the time and cognitive efforts of digging deeper into the code for the method’s context, as can be seen below:

This approach has a different mindset that you should adopt. Each method has something to tell, at least one new detail that the code doesn’t state, whether it’s a side effect, restriction, or any other abnormality. Writing about these detail will lead the developer to confront with the hidden details of its implementation and in times refactor the “code smell” parts. Thus, not only it helps the future readers of the code but also assists the writer to gain a better understanding of its implementation and improve it.

“Code never lies, comments sometimes do.” — Ron Jeffries

Have you ever heard that sentence? Indeed, comments get outdated when the code changes. The fact they do is because they are not considered as part of the code itself while they should. The code comments are coupled to it. It is in the developer’s responsibility to update it too. A fact should be checked during a code review.

Self-documenting code by geekandpoke

One last thing, the scope of the code is not relevant whether you should or shouldn’t put a comment on it. By that I mean, private access modified code should be documented too. Otherwise, we neglect the actual users of it, ourselves.

Without a doubt, for some developers, it will take time, practice, and getting used to this new way of thinking. But, in the long run, you’ll reap the rewards — in terms of code quality and a better understanding of your code circumstances, and eventually, your code will tell his story, its autobiography.