// My story
When I went to college I was taught that commenting my code was a “good thing”. Comments help you understand your code when you come back to it, and also make it easier for others to understand what the code does.
While in college, I never really saw the benefit of the comments, since all of our projects were of the variety of write it, get a grade, and throw it away. But still, I diligently commented my code, partially because it was part of my grade, but also because it was a best practice.
For many years I worked in companies that had different rules around comments in the code. Often there was a large comment block at the top of each class explaining what the class was, and how it was to be used, as well as a log of who changed it, when and why. At one such company, the build would throw a warning when these comments were missing. So, in an effort to reduce the number of build warnings, I started going through the code adding comments where the build complained. I made a huge impact on the number of warnings…but I’m not sure I did anything to actually improve the quality of the code with that effort.
Then, I started at a company where the developers didn’t believe in comments. At first I was surprised by this practice. Then, I was excited because I had a growing sense that these massive comment blocks at the top of classes were pretty useless anyway.
As I continued to work with these developers, I found I didn’t need to leave comments when I paid attention to how the code was written. I could often understand, even months or years later, what the code was doing given the method and variable names, and the associated tests. In our considerable code base, we only had a handful of comments.
I now fall into the “comments are a code smell” camp, though I am likely not as extreme as some others, I try to avoid commenting as much as possible. I am much more likely to refactor a piece of code to make it more readable than to add a comment. And, if I find comments in the code telling me what a snippet of code does, I am likely to remove it!
// When to use comments
As I said above, I don’t believe in commenting my code. However, there are times when comments are necessary (or at least useful).
You may be asking “How do I decide whether I should add a comment or not? What types of comments do I leave?”. There are only a few situations where I add comments to my code.
1) If I am using a third party library that is either a) complex, or b) doesn’t work as expected, I will add a comment explaining why the code is written the way it is.
2) If I am writing code that I just can’t seem to find a good way to refactor into self-explanatory code, I will add comment explaining what the code does (I really try to avoid explaining what), and why it is written this way.
3) If I am writing any type of library code that others will be using rather blindly, then I believe good comments (Javadoc) are essential to allow the user to understand how to use the code.
4) If there is a piece of code that has to be written in a not so obvious manner because of reasons not readily apparent in the class, I will comment why the code is written as is.
// Commenting out code
Don’t even get me started on commented out lines of code. If I see them, I delete them…no questions asked. Source control will allow you to get them back if you need them.
// Your Comments?
What is your stance on comments in code? Are there other scenarios that you feel deserve comments? Have you never seen code with well named methods and variables so you didn’t need to read the comments to figure out what it was doing?