To Comment or Not To Comment – Well, that is not the question

The palest ink is better than the best memory – Chinese Proverb

I came across a tweet a few days back. I couldn’t find the tweet to attach here but it stated something like

Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing

I feel like this is an interesting correlation. Something is better than nothing. But it made me wonder why do people think it is okay to have bad documentation? Can we say the same thing for code?

I have worked on a few legacy projects so far. For one of the projects, I had access to not a single developer who was initially involved in the development. That project was a nightmare for me. Not only because it did not have any documentation available, but most of the comments also were not in sync with the code either. And this is where I kind of disagree with having at least something even if it is bad. I think good documentation is as important as good code.

Comments are one of the forms of documentation and in my opinion most useful. Also, the most overlooked too. External documents like Design Document or Architecture Document usually go through a review process for approvals. More team members, including managers and maybe the client, are involved in the process so the document produced is decent but comments don’t get the same kind of attention.

That is a shame because comments are ‘by developers for developers’ kind of thing still we developers take it for granted. Mostly because more often than not the effort to write and maintain comments is not included in the plan. Take this as the first tip – Include effort to write and maintain comments as part of the plan.

I will be mentioning more tips but first, let’s see what comments are bad comments.

Types of Bad Comments

There are mainly four types of bad comments I see very often

Annoying comments

These are the most useless comments. I am pretty sure you have seen comments like

//checking if amount is greater than max amount 
if(amount > maxAmount)


//iterating on list of Accounts
for(Account account : accounts)

These comments are adding no value. Not only they are redundant but they are making code lengthier for no reason and now these have to be maintained too. That is why these comments annoy me the most. The developers who are writing comments like these, who do they think is reading the code? Even a non-programmer can get the sense of what is going on by reading just the code.

Subversion comments

Have you ever seen comments like

//adding null check to fix #M024 defect
if(accounts != null ){
      for(Account account : accounts)

Now, these are not totally useless comments but they don’t belong in the code. The code, in the first place, should have had the null check. Fixing a defect is not adding any new behavior to the code. Any comment which is related to fixing a defect should go in subversion comments when the code is being checked in. The classes should only contain comments for what they are doing, not the history of actions taken to make them do it.

Conversational Comments

These comments can be as annoying as redundant comments but sometimes they can be funny too. These are the comments where people are either showing their frustration about the code or they are just asking questions about it. For example

//Why do you have to have so many conditions in an if statement!!
if(a == b || (b == c && c != 0) || d == 1 .... blah blah blah)


try {
      blah; blah; blah;
} catch(Exception e){
      //Tod dont you think exception should be thrown from here? 

In the first case, it is most likely that the comment writer is working on legacy code and don’t have access to the person who wrote the code. In cases like these, instead of writing down your frustration, try and figure out what the condition could mean. Maybe you can write down what your understanding of the code is so the next person can utilize your knowledge too to figure it out.

In the second scenario, the comment writer knows the code writer by the first name! Now, this comment does not make sense to me at all. If you know the person, just talk to him or email him. The comment is still there that means Tod never saw it. And honestly, no Tod has ever replied to these comments (This is why people had to invent Notifications).

Out of Sync Comments

These comments are not simply useless but can cause harm too. And unfortunately, these are the most commonly found comments. These are the comments which were written with the first draft of code and were never updated again. The method name has been changed, the number of parameters has been changed, the return type has been changed, what the method does has been changed by now but the comment stayed the same.

These are mostly Javadocs (in java) or xmldocs (I guess this is what they call it in C#). The irony is these can be autogenerated by just typing ‘/** + enter’ in Java or ‘///’ in C#. Regenerate the comments whenever you are updating the signature of the method in case you are not using IDE’s refractor functionality.

Even worst is out of sync descriptions. The description gives readers understanding of the business requirements the method is accomplishing. It is what needs to be updated, validated and maintained regularly.

Now that we know what makes a comment bad, here are a few tips which can help you write better comments.


Apart from not writing the above-mentioned types of bad comments, you can use these tips to write more useful comments

Mention Reason and Goal

A comment should always explain why the code is written and what goal the code is accomplishing instead of what it is doing. The code itself is the answer to what. Use words like ‘because’ or ‘to’ in your comments. If you don’t have these words in your comment may be the comment is not required.

Explaining ‘why’ in comments will not only help the reader to understand the reason for the existence of the code, it will also make you re-analyze the code. Maybe this the method that you just wrote but you are not going to need (YAGNI).

Not every line of code needs a comment

I think a lot of people just believe that it is a good thing to write comments. Maybe because it will help people understand the fifty lines long method they have written or maybe to impress the code reviewer. Any which ways, they just get overboard with it. I have seen methods with every single line of code having a comment on top of it.

Here is a tip, if you think that the code is too complicated to understand without these comments then you should better think of simplifying your code instead of spending time on explaining it.

Also, most public methods are the one which contains a lot of business logic. Private or utility methods are just there to accomplish a certain step. So focus more on detailing out why the public method is written and what part of requirement it is accomplishing. Methods like ‘ObjectToXml’ or ‘GetSystemDate’ don’t really need any explanation so it is okay to not write comments on these methods.

Treat Comments As Code

Documents are the mirror image of the code.  – Pragmatic Programmer

All the principles that apply to the code, apply to the comments too. Comments should be written and maintained just like the code. For the code is read more times than it is written and comments are an important part of the process of understanding it, it only makes sense to treat comments as the code.

To summarise, don’t write comments to tell what the code is doing instead explain why the code is there and if your code needs comments to explain what it is doing then try and simplify the code.

Remember Good code does not need comments, the good code has comments.

P.S. – I know this post is as late as it can get. It is already another week. But as they say better late than never.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s