In recent posts Dan Dyer and Jeff Attwood took somehow different positions regarding what good comments are and if we need comments at all. I tend to agree that sometimes too much commenting is bad. But this is because the useful information in those comments is spread thin. I don’t think going to the extreme and having comments replaced with just relevant class/method naming is a good idea because you cannot express full intent in a class/method name. This is actually why you have to write some code inside the class or the method, isn’t it? I actually see a lot of value in approaching comments the way Avi Pilosof describes business commenting.
If code comments are so important then why so much code is poorly commented? To answer the question let’s see first why we comment our code in the first place:
- Make it easier for somebody else to understand what the code does
- Make it easier for the author to remember what his intentions were
- Explain the flow
- Explain or at least name the algorithms and the choice of algorithms
- Warn of unexpected behavior and side effects
- Help the maintenance programmer avoid creating problems when the code is fixed, modified or extended
- Explain the assumptions at the time of writing
- Explain the constraints at the time of writing
- Describe the requirements at the time of writing
- Explain the implementation decisions (why the code is designed/structured/written that way)
- Explain why the code was modified/fixed and mention the bug ID (at maintenance)
- Describe how the code was modified/fixed and what the desired effects are (at maintenance)
To summarize with only one word the reason for commenting code is maintenance!
At this moment we can postulate that comments addressing these issues are good comments. So characteristics of bad comments are, by contrast:
- Lack of comments
- Unmaintained comments – wrong comments misleading the reader
- Useless and bloated comments – stating the obvious and diluting the information
- Comments that focus only on how things are done not on why they are done that way
How bad comments are produced:
- People don’t want to write comments for reasons ranging from laziness to philosophy and perceived job security. Some programmers think their code is very clear while others don’t think at all about the future of that code. But the code is clear only in their minds since they already know all the requirements and the constraints.
- People don’t know how to write good comments. Some programmers really want to have comments but they don’t know what information to put there or, pressured by time constraints they simulate comments just to pass a code review. This is how bloated comments that explain nothing are born.
- People focus on how the code works instead of why the specific solution was picked. The developer wants to write comments, finds the time to write them but focuses on the methods of doing things and completely forgets to provide a glimpse into the reasoning behind the technical decisions.
- People forget to update/maintain comments. It happens more often than not – the code is changed but the comments are left around describing now gone functionality. This happens when new features are added, when the code is re-factored and when bugs are fixed.
- No incentive for writing good comments. I never heard somebody (a manager?) praising a programmer for the quality of the comments in the code. This also applies to code created by contractors or to code outsourced to another company.
- There is no interest in commenting the code properly. Sometimes the developer will never be the one to maintain the code. This quickly translates in lack of comments or in useless comments. Examples are developers in organizations that separate completely the development and the maintenance activities. Also contractors sometimes tend to have the same view on comments and as a result companies who outsource code development don’t get maintainable code if they don’t enforce some quality standards through reviews. And usually this is what happens since the review process is very time consuming. Contractors might be interested in doing the job as fast as possible but not in spending extra time in preparing the code for maintenance.
- Perceived lack of time to write good comments or to comment at all. Deadlines are the main killer of good documentation and good comments are also sacrificed in the process. Some people feel that commenting while writing the code interrupts their thought flow so they postpone it for the end, and then commenting actually never happens. Other people like to start by writing comments to outline what they have to implement. After the implementation is added they don’t review the comments to remove the obvious and to replace them with explanations.
- There is interest in lack of comments or in bad/useless comments. There are programmers out there who create useless comments (or use no comments at all) as a job security technique. This behavior can be observed also at some companies that provide open source free code and have a business model based on providing support and other services for that code. They feel compelled to provide as little free guidance as possible. Can you think of some examples? In the same spirit some contractors might try to get maintenance contracts in continuation of development contracts by obscuring information with lack of good comments.
First of all the quality of the comments in the code is an indicator of the overall code quality. I never encountered great code with bad comments. Good programmers keep the code neatly formatted and well commented.
The effects of poor or non-existing comments is felt long after the code is sent in production.Bad comments make the life of the maintenance developer hell. As a result of the poor understanding of the code intent bugs are introduced during maintenance and modification and can cause significant costs and business loss over the lifetime of a product.
How to write good comments
In order to write good comments first of all you have to care. You have to care about the quality of your work, about your customer and employer and you have to deeply care about the poor souls who will try to fix or change your code sometimes many years after you forgot you ever wrote it.
If you don’t care probably you didn’t make it this far in the article.
If you do care than take the list of “good comments” traits from the beginning of this post and pin it to the wall next to your monitor. Every time when you feel a piece of code is ready to be stored in your code repository review it thinking about all those points and try to make your intent and context as clear as possible for the next fellow programmer.
That list can be the base for a quality standard for comments in your company/group/team. Don’t make it a dogma and don’t transform it in bureaucracy.
Offer feedback to your colleagues and training to new team members. Make them care about their work and about the developer maintenance. You can be one at some moment in your life.