Commenting code: good, bad, evil

You have probably heard this: "A good code is self-documented . "

I earn more than 20 years by writing code, and I heard this phrase more often. This is a cliche .
')
And as in many other clichés, there is a grain of truth. But this truth has already been abused so much that most of those who utter this phrase do not understand what it really means.

Is she true? Yes

Does she mean that you should never comment on the code? No

In this article, we will look at different aspects of code commenting.

For beginners: there are two different types of comments. I call them documenting comments and explanatory comments .

Documenting comments

Documenting comments are intended for those who will use your code rather than read it. If you are making a library or framework for other developers, then you will need something like API documentation.

The further the API documentation is from your source code, the more likely it will become obsolete over time or become incorrect. It is best to embed the documentation directly into the code, and then extract it with some tool.

Here is an example of a documenting comment from the popular JS-library Lodash :

/** * Creates an object composed of keys generated from the results of running * each element of `collection` thru `iteratee`. The corresponding value of * each key is the number of times the key was returned by `iteratee`. The * iteratee is invoked with one argument: (value). * * @static * @memberOf _ * @since 0.5.0 * @category Collection * @param {Array|Object} collection The collection to iterate over. * @param {Function} [iteratee=_.identity] The iteratee to transform keys. * @returns {Object} Returns the composed aggregate object. * @example * * _.countBy([6.1, 4.2, 6.3], Math.floor); * // => { '4': 1, '6': 2 } * * // The `_.property` iteratee shorthand. * _.countBy(['one', 'two', 'three'], 'length'); * // => { '3': 2, '5': 1 } */ var countBy = createAggregator(function(result, value, key) { if (hasOwnProperty.call(result, key)) { ++result[key]; } else { baseAssignValue(result, key, 1); } }); 

If you compare these comments with the library's online documentation , you will see that everything is the same there.

When writing documenting comments, make sure you do it in accordance with the appropriate standard, and that comments can be easily distinguished from any inline explanatory comments that you can also add. Some popular and well-supported standards and tools are: JSDoc for JavaScript, DocFx for .NET, JavaDoc for Java.

The disadvantages of documenting comments include the fact that they are capable of “noisy” code, and programmers who are actively involved in the maintenance of the code, it is more difficult to read them. But on the other hand, most editors support “code folding” (code folding), which allows you to hide comments and only focus on code.


Collapse comments in Visual Studio code.

Explanatory comments

Explanatory comments are intended for everyone (including yourself in the future) who will accompany, refactor, or extend the code.

Often, explanatory comments are a sign of bad code. Their presence indicates the excessive complexity of the code base. Therefore, try to remove explanatory comments and simplify the code, because “good code is self-documented.”

Here is an example of a bad - albeit very funny - explanatory comment:

 /* * Replaces with spaces * the braces in cases * where braces in places * cause stasis. **/ $str = str_replace(array("\{","\}")," ",$str); 

Instead of decorating a confusing expression with a clever verse - written by dvukhtopnym amphibrach , no less - the author should spend time on a function that makes the code more readable and easy to understand. For example, you can make the function removeCurlyBraces , called from the function sanitizeInput .

Do not misunderstand, there are situations - especially when working on a very difficult task - when the soul asks for a bit of humor. But if you write a funny comment balancing a bad code, then it’s unlikely that someone will want to refactor or correct it later.

Do you really want to deprive other programmers of the pleasure of reading your witty little rhyme? Most of them will laugh and go about their business, ignoring the flaws in the code.

But there are situations when you come across a redundant comment. If the code is really simple and obvious, you do not need to add comments.

For example, do not do this:

 /* set the value of the age integer to 32 */ int age = 32; 

But it also happens: whatever you do with the code, an explanatory comment is justified. This usually happens when you need to add some context to a non-obvious solution. Here is a good example from Lodash:

 function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; } 

Or there are such situations: after much deliberation and experimentation, you realize that a solution that seemed naive is actually the best. In the future, other programmers will almost inevitably decide that they are smarter than you, and will begin to redo the code in order to realize later that your method turned out to be the best.

Sometimes you yourself can be such a programmer.

In such situations, it is better to save someone else's time and write a comment.

This comment is a stub perfectly illustrated described:

 /** Dear maintainer: Once you are done trying to 'optimize' this routine, and have realized what a terrible mistake that was, please increment the following counter as a warning to the next guy: total_hours_wasted_here = 42 **/ 

Of course, it is more entertaining than help. But you MUST leave comments, cautioning others against searching, it would seem obvious "better solution" if you have already tried and rejected other options. In this case, the commentary should describe what you tried to do and why you refused from such decisions.

A simple example in javascript:

 /* don't use the global isFinite() because it returns true for null values */ Number.isFinite(value) 

Evil

So, you read about good and bad, but what about the evil?

Unfortunately, in any profession you can feel frustrated, and when you write code to earn money, you may be tempted to express this frustration in the comments.

If you work with a sufficient number of code bases, then you will meet comments from cynical and depressive to gloomy and malicious.

From seemingly harmless ...

 /* This code sucks, you know it and I know it. Move on and call me an idiot later. */ 

... before intentionally abusive

 /* Class used to workaround Richard being af***ing idiot */ 

Such comments may seem funny, or at the time they help to reduce disappointment, but if they get into production, they will discredit the professionalism of the author and his employer, put them in a bad light.

Do not do this.