5 Do's and 3 Don'ts in Code Comments

[[135974]]

Code comments are arguably more important than the code itself. Here are some ways to ensure that the comments you write in your code are friendly:
Don’t repeat what the reader already knows

Comments that clearly explain what the code does are of no help to us.

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

To annotate reasoning and history

If the business logic in your code might need to be updated or changed later, that's where comments should be left :)

 /* 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++) {
 ...
 }

Do not write long comments on the same line

Nothing annoys developers more than having to drag the horizontal scroll bar to read comments. In fact, most developers simply ignore these comments because they are so inconvenient to read.

 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
 }

Put long comments above the logic and short comments after it.

Comments can be placed next to the code if they are less than 120 characters. Otherwise, the comment should be placed 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 ;
 }
 };
 }

Don't add unnecessary comments just for the sake of comments

Superfluous comments create confusion. Maybe in school you were taught to add comments to all statements, which will help developers understand better. But this is wrong. If anyone says this, you should give him a slap in the face immediately. Code should be kept clean and concise, there is no doubt about it. If your code needs to be explained line by line, then what you need to do most is refactoring.

 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  
 }

Notes should be spelled correctly

Don't make excuses for spelling mistakes in code comments. Your IDE can check spelling for you. If it doesn't have this feature, download a plugin and do it yourself!
Practice more

Practice makes perfect. Try writing helpful comments and ask other developers if your comments are useful. Over time, you will learn what makes a friendly comment.
To review other people's comments

We often overlook comments during code reviews. Don't be afraid to ask for more comments, you should question them. If everyone made it a habit to write good comments, the world would be a better place.
Summarize

Comments are a very important part of the development process, but we shouldn't comment for the sake of commenting. Comments should be useful, concise, and should complement the code. Comments should not be used to explain the code line by line, instead, they should be used to explain business logic, reasoning, and implications for the future.