I used to think that I didn’t need comments if I wrote self-documenting code. However, I have realized that I do write comments, and that I find

On Comments in Code

submited by
Style Pass
2021-06-15 18:30:03

I used to think that I didn’t need comments if I wrote self-documenting code. However, I have realized that I do write comments, and that I find them really useful. To see how many comments I write, and what kind they are, I wrote a script to analyze my git commits from the last six years. In total, seven percent of my committed lines contained a comment. This blog post has details on what constitutes good and bad comments, as well as more statistics from my script.

Part of the reason I was skeptical of comments was the prevalence of Javadoc-style comments. This style of commenting exists in other languages as well. Here is an example in Python that I just made up, but which is representative of this style:

The problem with most of these comments is that they convey very little information. Often it is just a repetition of the method name and parameter names in a few more words. These comments may be useful for API:s exposed externally, but in an application where you have access to all the source code, they are mostly useless. If you wonder what the method does, or what the valid input range for a parameter is, you are better off just reading the code to see what it does. These types of comment take up a lot of space without providing much value.

Instead of writing Javadoc comments, you are better off making the best possible use of method names and variable names. Each name you use can help explain what the computation is about and how it is done. One good reason for writing many small methods instead of one large method is that you have more places to use descriptive names, something I have written about here.

Leave a Comment