10 Rules For Writing Clean Codes

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.?The common reason a programmer use comment is to explain a bad code. But

it’s a bad habit, we had better clean it rather than commenting on a

messy block of code. Clear code with a few comments are far better than cluttered and complex code with lots of comments.

““Don’t comment bad code — rewrite it.” — Brian W. Kernighan and P. J. Plaugher”

Let's take a look at some rules to follow and the common pitfalls to avoid while programming.

1. Don’t Yell

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

1. //------------- YOU MUST SEE THIS COMMENT ------------
3. someFunction(){
4. // do stuff
5. }

2. Multi-line Comment vs. Single-Line Comment

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

The following comment is bad:

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

Instead do this:

1. /*
2. This is also another comment which is long
3. but this comment is written as a multi-line comment
4. */

3. Lying/Misleading Comment

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

1. someFunction(n) {
2. ... Some Other Code
4. // We don't divide by 0 in order to stop crashes.
5. return 1 / n
7. }

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!

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.

1. // if(something){
2. // doSomething()
3. // }

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

5. Explain in Code, Not in Comments

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

1. // checks if employee is eligible for bonus
2. if(employee.salary > 20000){
4. }

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

1. if(employee.isEligibleForBonus(salary)){
3. }

6. 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.

1. // TODO clean this later!
2. // Need to extract into smaller functions
4. someFunction(){
5. // do stuff
6. }

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

7. 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.

1. /** Added By Faisal */
3. someFunction(){
4. // do stuff
5. }

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.

8. Comments Should Explain Why, Not How

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

1. # convert to cents
2. a = x * 100
4. # avg cents per customer
5. avg = a / n
7. # add to list
8. avgs < avg
9. t += 1

But the same code can be rewritten as follows:

1. total_cents = total * 100
2. average_per_customer = total_cents / customer_count
4. track_average(average_per_customer)

9. 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.

10. 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!

#softwareengineering #Developers #engineers #frontenddevelopers #dataanalytics #cybersecurity #backenddevelopers #programmers