How To Write Good Comments

Writing good comments is a skill, which many developers seem to neglect. What makes a good comment?

Why do we write comments?

Comments are not for you, they’re for me (the Dev Manager) or your co-workers. The whole reason you’re writing comments is for the sanity of the next person to look at your code; they give another developer insight and guidance into your code. 

Why is that a good thing? It allows someone else to work on your code with a deeper understanding of your thought process, allowing them to continue making logical choices on your initial design choices. 

With that in mind, I think we need to define a few basic rules to get you started with creating good comments. 

Rule #1: Why, not what…

The most important rule for any new developer is to focus on why, not what. Let that sink in. 

If you take nothing else from this article, this is the most important rule for comments. 

Lets look at the following code: 

if (a == b)

price = prices / vatRate;

price = prices * specificConditions;

price = prices * vatRate

endif

Bad Comments

There are no comments on this code, so lets add some to get us started. 

if (a == b)

price = prices / vatRate; //remove vat

price = prices * specificConditions; //Add it back on

price = prices * vatRate //add vat

endif

What makes these comments “bad”?

They are are describing what is happening, not why. When I’m learning a new codebase or doing a code review, I would rather know why.

I can read code just fine; I’m up to date on the latest ES6 syntax and I can decipher obscure operators with Google. What I can’t do is read minds. WHY are you removing VAT, adding something on and then adding the VAT back on?

Good Comments

//This operation adds provider commission rates to the prices. Used in reporting callBack for async operations, cannot do it later on due to synch issues

if (a == b) 

price = prices / vatRate;

price = prices * specificConditions;

price = prices * vatRate

endif

As you can see, we’re now addressing why, which gives the next developer to work on the code the information they need. They can jump straight to the callback function or at least keep it in mind for later perusal.

Don’t keep someone guessing, or force to them to make assumptions. Be clear, concise and explain your thinking as necessary.

Rule #2: Code is NEVER self documenting

This one shouldn’t need to be on here, but I’ve seen more than enough developers argue their code is self documenting.

No….it’s not!!

You may think it’s a simple piece of code, and it probably is to YOU.

This doesn’t mean you’re the god of programming, it means you wrote the code and have used a thought process (or not) to achieve the end result. The next person may wonder why you’ve looped through that array 50 times instead of using a recursive loop.

Is there a reason? Only you know and that’s the problem.   

Rule #3: The Early Bird

Start your comments early and revise/review as you go. This way you don’t have to go back before you push it into the repo and start the comments from scratch. Writing comments is an iterative process and you should be writing as you go.  

I tend to write a draft set of comments per function and then ensure I’ve ticked off the most important rule. Why, why, why…..

After the comments make sense, move on but don’t leave it all to the end. You’ll forget to do it, and the next dev will be tapping you on the shoulder within 5 minutes of checking out your branch. 

Rule #4: Warn about landmines

If you know the code you’re working on has a big effect on other parts of the codebase, say something. 

Small innocuous pieces of code have a habit of being an integral part of the code base. New developers faced with an unfamiliar codebase will appreciate a heads up.

Rule #5: Don’t waffle

Too many comments are almost as bad as too many. If every line of code has a comment, it’s easy to miss the really important stuff. It also indicates the Dev doesn’t really understand where they’re going with their code.

Why do you need to comment a simple if statement? You don’t. Lets look at some examples.  

//This function is meant to match example comments, then clean them then return them if we think they are okay to be displayed

function commentExamples(stringIn) //We send in a string, because it’s what was asked for by Jim, I don’t know why

{

switch(stringIn){ //Start the switch statement

case(‘commentOne’)://If we match this one, we shouldn’t return  anything

return false;//return false

break;//shouldn’t need this.

default://Default option, not sure if need this?

return false;//Going to return  false

break;

}

return false;//lets return false, Jim said it was something to do with us receiving blank schema from one of the suppliers

}

You may laugh but this isn’t far from something I saw on a previous project. Pretty much all of those comments are unncessary. They don’t explain why the code is doing what it’s doing, and the one useful piece of information is hidden away at the end. 

Jim obviously gave this person a job to do, but they didn’t know why. Now, neither do we. 

Keep your comments short and succint, but if there’s a backstory put a brief history in there with some resolutions. I.e. go and find out (from Jim) why the schemas were coming back blank and from which supplier. 

Practice, practice, practice…

As I mentioned at the beginning, writing good comments is a skill; the same as programming. 

Practice makes perfect, and this skill bumps you up from a good developer to a great developer.

It’s also something that is never wasted time and will be useful for your entire career as a developer. It doesn’t matter is NodeJs becomes obsolete, or Java eventually goes the same way as ActionScript. Writing good comments is a skill that will follow you to all the new and exciting languages in the future.