5 do's and 3 don'ts in code comments

　Code comments can be said to be more important than the code itself. Here are some ways to make sure 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 not helpful to us.

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

　Be sure to comment explaining reasoning and history

　If the business logic in the code may need to be updated or changed in the future, then you should leave a comment:)

/* 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 write very long comments on the same line

　There is nothing like dragging The horizontal scroll bar to read comments is even more annoying to developers. In fact, most developers choose to ignore such comments because they are really 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
}

Place long comments above the logic and short comments at the back

　 If the comments do not exceed 120 characters, they can be placed next to the code. 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 for the sake of comments

Superfluous comments can cause confusion. Maybe in school you were taught to comment out all statements, which would help developers understand better. But this is wrong. If anyone says that, give him a slap in the face right away. It goes without saying that code should be kept clean and concise. If your code requires line-by-line explanation, then the most important thing you need to do is 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
}

Comments should be spelled correctly

Don’t make excuses for spelling errors in code comments. The IDE can check spelling for you. If you don’t have this function, then download the plug-in and do it yourself!

　Practice more

　Practice makes perfect. Try writing some useful comments and ask other developers if your comments are useful. Over time, you'll learn what constitutes a friendly comment.

　To review other people’s comments

　 During code review, we often neglect to check comments. Don't be afraid to ask for more comments, you should ask questions. If everyone developed the good habit of writing good notes, the world would be a better place.

　Summary

　Comments are a very important part of the development process, but we should not comment for the sake of comments. 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.