Okay so what's up with comments? Devs seem to hate them. Infamous Cleanest Coders do not write comments, right?
I disagree. I think comments are great. A good comment can make my day wonderful. Look at all these beauties!
But this is only opinion against opinion. Even if I'm not the only one advocating for writing comments, it's still unfounded opinions. Can we find evidence that commenting is good?
Thankfully for me, there's a lot of research on the subject. A quick search in Empirical Software Engineering yields 44 pages of results!
Most of the articles are positive towards commenting code. This one states that:
Existing studies show that code comments help developers comprehend programs and reduce additional time spent on reading and navigating source code.
Unfortunately, I have to pay 40 euros to have access to it... This is extortion. There's an open-access article with a lot of references. I use it as a starting point.
Firstly, i'll skim through all the papers. Then i'll devise a documented opinion on the matter.
Documentation is crucial for software development. It helps understand other people's code, without reading it. This is critical for libraries. Imagine having to choose between a well-documented library and some library without documentation.
Also, engineers prefer writing the documentation close to the code. So comments are the most obvious way to write documentation.
These are great but the studies' core subject is comment reuse in object-oriented languages. This is not what i'm looking for.
This paper is an excellent pointer to other references though.
This article is promising at first: analyzing the process of how developers analyze code. It is a weak article for me: it only evaluates students.
It shows that they went back and forth between the code and the documentation. That's it...
This paper suggests that 2 types of comments are bad:
It has a great survey question section to see what was evaluated:
Survey 2: What to do with the comment?
This paper does not discuss much how this taxonomy helps understand comments. Which is quite disappointing... They used a magical metric (c_coeff) to know if comments were good or not.
I don't know what to think about this paper. I either read it too quickly or it's not interesting, but I couldn't extract useful information.
This study is good. 48 experienced programmers are given a random piece of code. The code is either commented or not. The participants have to answer 20 questions about the code. If the code had comments, participants answers more correctly.
The experiment is an easy task. It's the best experiment showing that commented code is better than uncommented code.
This experiment was reproduced with concording results in a later study
Note: according to the last paper's surveys, comments in these studies are:
This is interesting because one might think only external context could be useful.
Combined observation of 28 professional devs and survey of 1477 respondents. This study is on program comprehension. Many studies already tackle the subject before but with smaller samples.
The result of the study: developers use informal tools to get knowledge. They prefer code comments, commit messages, emails, tickets, etc. The appropriate knowledge is usually not documented.
I haven't learned much from this paper :shrug:
This study is pretty good. Its scope is limited which makes it simple to read and understand. It surveys the artifact used by developers to maintain software.
It would be great if this study was reproduced. It does not prove much but: devs use all sorts of documentation.
The four most important artifacts are:
It does not say which is best. It does say one thing though: documentation is key for maintenance.
My conclusion is: not much can be said about comments. Most studies suffer from flaws: either unreproduced results (, , etc.), old studies (), small or non-representative samples (), contradicting results ( and ), etc. None is strong and all are open to interpretation.
It does not mean that nothing can be said. Every paper shows that comments are useful. They are part of documentation which helps comprehension.
All the following sentences are not supported by science:
Nevertheless, the studies are pretty clear on one thing: comments are good. They are a form of documentation which are the closest to the code.
The studies do not say what kind of comments are the most useful. Until the facts are settled, you'll still have to discuss it with your team. Please do. Discuss comments with your teammates. Agree on how to write comments to make sure you do write them.