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

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.

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

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 :)

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

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.

  1. function Person(name) {
  2. this.name = name;
  3. 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
  4. }

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.

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

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.

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

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.

<<:  Google's Android M secret weapon: built-in theme engine

>>:  Learn more! A collection of iOS trivia

Recommend

Professor Li Guoping: Twenty Lectures on Financial Knowledge

Professor Li Guoping: Twenty Lectures on Financial...

iOS 16.5 update push, this feature will be disabled

Early this morning, Apple pushed the iOS 16.5 Bet...

From a product perspective, how to write 10W+ high-quality articles

Nowadays, public accounts have become one of the ...

1/3 of PC gamers choose 1080p. What about you?

The battle over the image quality of the new gene...

Online Love Saint Group 38 Dating - Attraction - Chatting - Temptation

If you feel that women's tempers are always i...

Why do we need quantum computing?

Author's Note At the request of a friend, I w...

Google advertising system, Google advertising process!

Some people say that knowledge changes destiny an...

Milk is for calves, not humans? Nine myths and facts about dairy products →

Dairy products are very nutritious and can be an ...

Tik Tok's latest transfer technology for WeChat Moments, which charges 138 yuan

The latest Douyin transfer technology charges 138...