---
I used to think that I didn’t need comments if I wrote self-documenting code. However, I realized that I do write comments and find them genuinely useful. To see how many comments I write and what kinds they are, I created a script to analyze my Git commits over the past six years. In total, seven percent of my committed lines contained comments. This post includes details about what makes good and bad comments, along with additional statistics from my script.
Javadoc Is the Most Useless
One of the reasons I was skeptical about comments was the prevalence of Javadoc-style comments. This style exists in other languages as well. Here’s a Python example I just came up with, but it represents this style:
image
The problem with most of these comments is that they carry very little information. They often just repeat the method name and parameter names in slightly different words. These comments can be useful for public APIs, but in an application where you have access to all the source code, they are mostly useless. If you’re curious about what a method does or what input range is allowed, it’s usually better to read the code itself. These types of comments take up a lot of space but provide little value.
Self-Documenting Code
Instead of writing Javadoc-style comments, it’s better to make maximum use of method names and variable names. Every name you choose can help explain what’s going on and how it works. One strong reason to write many small methods instead of one large one is that it gives you more opportunities to use descriptive names.
When to Comment
Writing self-documenting code will help you in the long run. However, there are cases where additional information is useful. For example, a comment explaining the use of batching in the code below:
image
Another example:
image
You often hear the advice “write comments about WHY, not WHAT.” While this probably describes most of my comments, it’s not exactly how I think about it. Instead, I usually write a comment when something is particularly complex—either in the domain itself or in how the implementation works.
A common recommendation from the “no comments needed” crowd (which I used to belong to) is to rewrite the code so that comments are unnecessary. However, this isn’t always possible. Sometimes the domain is just too complex. Sometimes rewriting the code would take far more effort than simply adding a comment.
Another complaint about comments is that they can get out of sync with the code, making things harder to understand rather than easier. While this does happen occasionally, it hasn’t been a major issue for me. In almost all the cases I analyzed, the comments were still valid—and very helpful. Every time I came across one of these comments, I was glad I had written it. It doesn’t take long to forget the details and nuances of a problem you’ve solved, and having a comment with extra context is great.
Logs as Comments
Sometimes you get a “free” comment if you log a meaningful message. In the example below, the log statement explains what happened, so an additional comment isn’t necessary:
image
Comment Analysis
When I first thought about checking how many comments were in all my commits, I figured one line would be enough to find comments in my Python commits (I only use # for comments):
git log --author=Henrik -p | grep '^+[^+]' | grep '#' | wc -l
However, I soon realized I needed more detailed insights. I wanted to distinguish between end-of-line comments and full-line comments. I also wanted to know how many “comment blocks” (consecutive comment lines) I had. I decided to exclude test files from the analysis. I also made sure to exclude any commented-out code (unfortunately, there were a few cases of that). In the end, I wrote a Python script for the analysis. The input for the script was the output of:
git log --author=Henrik -p
From the results, I found that 1,299 out of 17,817 added lines contained comments. There were 161 end-of-line comments and 464 single-line comments. The longest comment block was 11 lines, and there were 96 cases of comment blocks with three or more consecutive lines.
Conclusions
I used to think that writing well-named functions meant comments were unnecessary. However, looking at what I actually did, I noticed that I tend to add comments in complex or non-intuitive parts of the code. Every time I return to these parts of the program, I’m glad I took the time to add comments—they turned out to be very helpful!
I used to think that I didn’t need comments if I wrote self-documenting code. However, I realized that I do write comments and find them genuinely useful. To see how many comments I write and what kinds they are, I created a script to analyze my Git commits over the past six years. In total, seven percent of my committed lines contained comments. This post includes details about what makes good and bad comments, along with additional statistics from my script.
Javadoc Is the Most Useless
One of the reasons I was skeptical about comments was the prevalence of Javadoc-style comments. This style exists in other languages as well. Here’s a Python example I just came up with, but it represents this style:
image
The problem with most of these comments is that they carry very little information. They often just repeat the method name and parameter names in slightly different words. These comments can be useful for public APIs, but in an application where you have access to all the source code, they are mostly useless. If you’re curious about what a method does or what input range is allowed, it’s usually better to read the code itself. These types of comments take up a lot of space but provide little value.
Self-Documenting Code
Instead of writing Javadoc-style comments, it’s better to make maximum use of method names and variable names. Every name you choose can help explain what’s going on and how it works. One strong reason to write many small methods instead of one large one is that it gives you more opportunities to use descriptive names.
When to Comment
Writing self-documenting code will help you in the long run. However, there are cases where additional information is useful. For example, a comment explaining the use of batching in the code below:
image
Another example:
image
You often hear the advice “write comments about WHY, not WHAT.” While this probably describes most of my comments, it’s not exactly how I think about it. Instead, I usually write a comment when something is particularly complex—either in the domain itself or in how the implementation works.
A common recommendation from the “no comments needed” crowd (which I used to belong to) is to rewrite the code so that comments are unnecessary. However, this isn’t always possible. Sometimes the domain is just too complex. Sometimes rewriting the code would take far more effort than simply adding a comment.
Another complaint about comments is that they can get out of sync with the code, making things harder to understand rather than easier. While this does happen occasionally, it hasn’t been a major issue for me. In almost all the cases I analyzed, the comments were still valid—and very helpful. Every time I came across one of these comments, I was glad I had written it. It doesn’t take long to forget the details and nuances of a problem you’ve solved, and having a comment with extra context is great.
Logs as Comments
Sometimes you get a “free” comment if you log a meaningful message. In the example below, the log statement explains what happened, so an additional comment isn’t necessary:
image
Comment Analysis
When I first thought about checking how many comments were in all my commits, I figured one line would be enough to find comments in my Python commits (I only use # for comments):
git log --author=Henrik -p | grep '^+[^+]' | grep '#' | wc -l
However, I soon realized I needed more detailed insights. I wanted to distinguish between end-of-line comments and full-line comments. I also wanted to know how many “comment blocks” (consecutive comment lines) I had. I decided to exclude test files from the analysis. I also made sure to exclude any commented-out code (unfortunately, there were a few cases of that). In the end, I wrote a Python script for the analysis. The input for the script was the output of:
git log --author=Henrik -p
From the results, I found that 1,299 out of 17,817 added lines contained comments. There were 161 end-of-line comments and 464 single-line comments. The longest comment block was 11 lines, and there were 96 cases of comment blocks with three or more consecutive lines.
Conclusions
I used to think that writing well-named functions meant comments were unnecessary. However, looking at what I actually did, I noticed that I tend to add comments in complex or non-intuitive parts of the code. Every time I return to these parts of the program, I’m glad I took the time to add comments—they turned out to be very helpful!
