Comments in code are arguably more important than the code itself. Future you will thank present you if you are a good commenting citizen. I have read a ton of code in my lifetime and have come across some pretty amazing comments, but mostly awful ones. Here are some ways you can ensure you are writing good comments in your code:

Comments Do’s and Dont’s

Don’t tell the reader what they already know

Comments that say exactly what the code does are not helpful.

// If the color is red, turn it green if (color.is_red()) { color.turn_green(); } 1 2 3 4 // If the color is red, turn it green if ( color . is_red ( ) ) { color . turn_green ( ) ; }

Do comment reasoning and history

If there is business logic in code that could be impacted on future updates or changes, leave a comment and more importantly, create a future ticket to address it 🙂

/* The API currently returns an array of items even though that will change in an upcoming ticket. Therefore, be sure to change the loop style here so that we properly iterate over an object */ var api_result = {items: ["one", "two"]}, items = api_result.items, num_items = items.length; for(var x = 0; x < num_items; x++) { ... } 1 2 3 4 5 6 7 8 9 10 11 12 /* The API currently returns an array of items even though that will change in an upcoming ticket. Therefore, be sure to change the loop style here so that we properly iterate over an object */ var api_result = { items : [ "one" , "two" ] } , items = api_result . items , num_items = items . length ; for ( var x = 0 ; x < num_items ; x ++ ) { . . . }

Don’t make long comments on one line

Nothing bothers a developer more than having to scroll horizontally to read comments. In fact, most developers will just ignore them because it is an inconvenience.

function Person(name) { this.name = name; this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let's do it } 1 2 3 4 function Person ( name ) { this . name = name ; this . first_name = name . split ( " " ) [ 0 ] ; // This is just a shot in the dark here. If we can extract the first name, let's do it }

Do put longer comments above logic and short comments to the side

This is sort of like the statement above, but I wanted to spell it out. Short comments belong next to code if and only if it doesn’t exceed 120 characters on one line. Otherwise, put the comment directly above the statement.

if (person.age < 21) { person.can_drink = false; // 21 drinking age /* Fees are given to those under 25, but only in some states. */ person.has_car_rental_fee = function(state) { if (state === "MI") { return true; } }; } 1 2 3 4 5 6 7 8 9 10 11 if ( person . age < 21 ) { person . can_drink = false ; // 21 drinking age /* Fees are given to those under 25, but only in some states. */ person . has_car_rental_fee = function ( state ) { if ( state === "MI" ) { return true ; } } ; }

Don’t add unnecessary comments for the sake of commenting

Commenting creates clutter. You may have been taught in school to add comments to everything because it will help the developer understand it better. This is wrong. Do me a favor and go de-pants whomever taught you this. Your code should be clean and concise enough in a way that it is self-explanatory. If your code needs to be explained line-by-line, you’re in dire need of a refactor.

if (person.age >= 21) { person.can_drink = true; // A person can drink at 21 person.can_smoke = true; // A person can smoke at 18 person.can_wed = true; // A person can get married at 18 person.can_see_all_movies = true; // A person can see all movies at 17 //I hate babies and children and all things pure because I comment too much } 1 2 3 4 5 6 7 if ( person . age > = 21 ) { person . can_drink = true ; // A person can drink at 21 person . can_smoke = true ; // A person can smoke at 18 person . can_wed = true ; // A person can get married at 18 person . can_see_all_movies = true ; // A person can see all movies at 17 //I hate babies and children and all things pure because I comment too much }

Do spell things correctly in your comments

There isn’t any excuse to misspell words in your code comments. Your IDEs should have spell checkers. If they don’t, for the love of God, download a plugin and check yourself!

Do practice

Practice makes perfect. Try creating useful comments and asking another developer if the comment is useful to them. Over time, you’ll get a better sense of what constitutes a “good” comment.

Do review other comments

Comments are often overlooked in code reviews. Don’t be afraid to ask for more comments in code and question the ones that are there. If everyone can get in the habit of writing better comments, more butterflies will fly and less babies will die. That’s probably not true, but leave a comment if you disagree.

Summary

Comments are a very important part of the development process and you should always leave a comment/docstring per the standards of each development language (think about IDE integration and code sense), but don’t comment for the sake of commenting. Comments should be useful, concise and complement your code. Comments should not have to explain your code line-by-line, rather, they should aide in explaining business logic, reasoning, and future implications.