15 Rules for Writing Clean Comments

To read more articles like this, visit my blog

Comments in code have been there since the beginning of programming. But in today’s world, do we need them? Some would argue that we shouldn’t have comments in our code at all.

Well, it’s true. Code should be self-documenting. But still, there are some instances when we need to add comments. About this Uncle Bob says,

“Comments are an unfortunate necessity, not great achievements.”

Today, we’ll look at some rules to follow and the common pitfalls to avoid while programming.

1. Multiline Comment vs. Single-Line Comment

Whenever possible, try to write long comments as multiline comments.

The following comment is bad:

// This is a long comment 
// Which is written as multiple single line comment.
// Always remember it's bad

Instead, do this:

/*
  This is also another comment which is long
  but this comment is written as a multi-line comment
*/

2. Nonlocal Comment

Here’s an example of bad comment. The default time out is 5000, but it doesn’t specify where this value was set.

// if timeout is not set then it defaults to 5000

int timeout = 2000;

Never comment about some code that’s not present. Instead, try to provide some context.

// if timeout is not set then it defaults to 5000 which is defined in proerties file

int timeout = 2000;

3. Favor Long Names Over an Explanatory Comment

Sometimes, we try to avoid writing long names and explain them in the comments.

// it calculates the dining set 
// with the sum of table and chairs

dset = tbl + chr 

Instead, write long explanatory names, if needed:

dining_set = number_of_tables + number_of_chairs;

4. Never, Ever, Ever Comment Out Code!

This is the ugliest practice of all. We sometimes comment out code, thinking we (or someone else) might need that piece of code later.

// if(something){
//    doSomething()
// }

We have the version-control system for a reason. Use that.

5. Lying Comment

Don’t write a comment that doesn’t tell the whole truth.

someFunction(n) {
  ... Some Other Code

  // We don't divide by 0 in order to stop crashes.
  return 1 / n

}

Here we’re saying that we’re not dividing by 0, but where did we ensure that? Maybe we never supply 0 as a value of n, but that’s not understandable from this function.

So never comment on something that’s confusing — or maybe a lie!

6. Explain in Code, Not in Comments

No comment can compensate for a bad piece of code. Don’t comment on some logic.

// checks if employee is eligible for bonus
if(employee.salary > 20000){

}

Instead, extract out the logic into a separate, meaningful function.

if(employee.isEligibleForBonus(salary)){

}

7. Don’t Make Comments Harder Than the Code

Never comment something harder than the code itself. Like the following one:

// this is a utility function that provides us the proper validation 
// for date and time and check the logic

boolean checkIfDateIsValid()

8. Never Comment the Obvious

Some comments are so obvious that it’s ridiculous to comment them out.

try{
    doSomething()
}catch{
   // exception caught
}

Obviously, inside the catch block, we catch an exception. There’s no need to point that out.

9. Avoid To-Do Comments

Try to avoid TODO comments as much as possible. Because history shows we almost never go back to do that thing later. So try to avoid TODO comments as much as possible.

// TODO clean this later!
// Need to extract into smaller functions

someFunction(){
  // do stuff
}

You never do the things on your to-do list, anyway.

10. Stupid Comments

Here are some examples of absolutely stupid comments. I guess I don’t need to explain why.

/** The Name */
private String name;

/** The Age  */
private String age;

11. Don’t Yell

Don’t yell in comments. If you yell unnecessary things, your other comments can become less important

//------------- YOU MUST SEE THIS COMMENT ------------

someFunction(){
  // do stuff
}

No need to yell. Keep it simple.

12. Blaming Comments

Some codebases have a rule that every developer should keep their name at the top of the file so people can find out later who did what.

/** Added By Faisal */

someFunction(){
  // do stuff
}

It may have made sense 30-40 years ago, but in our current age of version control, we don’t need this anymore. So don’t do that.

13. Comments Should Explain Why, Not How

The following is an example of bad commenting that tries to explain the procedure.

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

But the same code can be rewritten as follows:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

14. Documentation Comments

Today’s modern languages give us some awesome tools with which we can generate HTML documentation from comments. This sometimes allures developers to write bad documentation comments.

15. Don’t Comment

The most important rule of commenting is to avoid it in the first place.

Make the code speak for itself.

Try to avoid commenting on code as much as possible. Following this rule can lead you to a cleaner codebase that you can be proud of.

Conclusion

Thank you for reading this far. I hope you found something useful in this article.

Have a nice day!

Get in touch with me via LinkedIn or my Personal Website.