A really good comment is the one you managed to avoid. (c) Uncle Bob
Lately, I’ve been feeling really tired of hot discussions on if it’s necessary to add comments in the code. As a rule, there are self-confident juniors with the indisputable statement as: “Why not to comment it, it will be unreadable without the comments!” on one side. And experienced seniors are on the other side. They understand that if it’s possible to go without the comments than “You better, damn it, do it in this way!” Probably, many developers got comment cravings since they’ve been students when professors made them comment every code line, “to make the student better understand it”. Real projects shouldn’t contain a lot of comments that only spoil the code. I don’t agitate for avoiding comments at all, but if you managed to write the code that doesn’t need comments, you can consider it your small victory. I would like to refer you to some good books that helped form my position. I like and respect these authors and completely share their opinion.
Steven C. McConnell, Code Complete
Robert Martin, Clean Code: A Handbook of Agile Software Craftsmanship
Dustin Boswell, Trevor Foucher, The Art of Readable Code (Theory in Practice)
So, what makes me mad about the comments? Here are some main statements:
- Comments spoil the code itself, make it less readable;
- Comments require time for writing and maintenance;
- Comments lie (starting from the improperly composed comments and ending with the obsolete ones)
Basically, I agree that in some cases the comments are necessary. But the less such cases exist the more beautiful your code is. Besides, writing a good comment is the art as well. Unfortunately, just few developers have that skill, the rest of them write the comments anyhow. The benefit of such commenting is quite doubtful. Isn’t it better not to spend time and effort for writing a good comment but to spend it for re-writing the code in the way it could go without any comments?
Let’s discuss some typical scenarios and define to what extent the comment is necessary. I provide C# code, but this is not that critical for this article.
When you can go without the comments
Comments that repeat code
Let’s have a look at the following code:
// The method receives elements array at the input
public int CalcSumOfElement(int[] elements)
{
int result = 0; // Creating a special variable for the result
int n = elements.Length; // Defining array length, i.e. number of elements
for (int i = 0; i < n; i++) // Running cycle for all elements
result += elements[i]; // Adding an element to the result
return result; // Returning the result
}
Of course, this sample is fake, but unfortunately, I don’t overdo. I saw such code quite often. In this sample, the comments don’t provide any new information; everything can be understood from code. And reading this code without the comments would be much easier. I don’t even say about maintenance of such code: it’s quite tiresome to support this level of commenting. Most likely, when the code becomes more sophisticated half of code won’t have comments, the rest of code will include obsolete comments.
Comments explaining syntax
Here is the sample:
{
private int value; // This is a private field, it’s not available from outside
// This is a constructor
public Item(int twoValue)
{
value = twoValue >> 1; // Two characters don’t mean bitwise sift to the right
// so, we divide the value in two
}
}
If this is a laboratory research of a fresher, it’s ok. But if this is the production code and your developers need such comments, I’ve got bad news for you. Probably, this article is not for you.
Comments explaining standard classes
// It represents a set of elements
// We can easily find out if an element is included in this set
// More information on hash-tables can be found in wikipedia:
// http://ru.wikipedia.org/wiki
// /%D0%A5%D0%B5%D1%88-%D1%82%D0%B0%D0%B1%D0%BB%D0%B8%D1%86%D0%B0
If a programmer really doesn’t know designation of some standard class or method, he can always use Google search / read documentation / ask an associate. Most good developers already know it. That’s why I strongly doubt usefulness of such comments.
Comments explaining improper names
public void DoIt()
I agree that it’s not always possible to name a class/method/property/variable properly. And if the project deadline is yesterday, there is no time to think over good names. Let’s take some arbitrary name and explain what’s happening in the comments. This is much easier and quicker! Or you will spare a minute or two to give an understandable name?
Comments explaining a paragraph
I often hear the following phrases: “This method is 300 lines, it does lots of things. You can’t understand it without the comments. I will comment every 10 lines”. If this is the case, you, probably, do something wrong. May be it’s better to divide this big 300-lines method into several smaller methods. And give an understandable name to every small method. In this way you won’t need the comments.
Comments explaining constants
{
return hours * 3600; // 3600 – this is amount of seconds forming an hour
}
In this variant, availability of the comment is a more adequate variant that just a figure added to the code and meaning something. But it’s even better to create a named constant which name made everything understandable.
For example, in this way:
public int GetSeconds(int hours)
{
return hours * SecondsInHour;
}
Comments not related to programming
I like a story from “Code Complete” about how a developer tried to understand the following comment for the whole night:
MOV AX, 723h ; R. I. P. L. V. В.
Some months later he met the author of this code and learnt that the comment meant the following: «Rest in peace, Ludwig van Beethoven» as 723 is a hexadecimal view of the year of Beethoven’s death. Unfortunately, some programmers think that the code is some kind of a forum where they can communicate. Some of them try to be witty (nearly telling funny stories), others tell something about themselves (for example, “It’s 3.00am right now and I am still writing this class as I am fond of programming”). You don’t do it in this way; there are hundreds of other communication means. If the comment is included in the project it should add some value to this project.
Comments containing thoughts
It happens that a comment contains some smart ideas that are very useful. But very often this is not the case:
{
// Well, this is a very useful method
// It executes main logic of this class.
// At first I wanted to name it Run.
// But then I thought that Run means “to go quickly”.
// And this method doesn’t run, it’s very slow.
// I was thinking about it when washing the dishes.
// And when I finished washing the dishes and got back to my computer I renamed the method to Main.
// This is the main method of this class, let it be Main.
}
To be continued…
