15 Rules for Writing Clean Comments
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. The 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