Code comments, can be said to be more important than the code itself. Here are some ways to make sure that you write in the comments in the code are friendly:

Do not repeat readers already know the content of

Comment can clearly describe what the code is doing is not helpful to us.

If the color is red, turn it green

if (color.is_red()) {

color.turn_green();

}

Explanatory reasoning and history

If the business logic in your code may need to be updated or changed, that 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++) {

...

}

Same line don't write very long

Drag the horizontal scroll bar to read the comment nothing developers even more heinous. In fact, most developers will choose to ignore these comments, because reading is really inconvenient.

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

}

Long comment should be placed in the logic above, short annotations in the back

Note If you do not exceed 120 characters that can be placed next to the code. Otherwise, they should direct comments to the statement above.

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;

}

};

}

Not to comment while adding unnecessary comments

Superfluous comment was confusing. Maybe in school teacher teaches you to add comments to all the statements, which will help developers understand better. But this is wrong. Who's to say, you pitch to him at once two big erguazi. Code should be clean and simple, this is beyond doubt. If your code line-by-line explanations, then you need to do is to 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

}

Note to correct spelling

Don't excuse spelling errors in the code comments. IDE can check spelling for you. If you do not have this feature, so go download the plugin yourself!

To practice

Practice makes perfect. Try to write some useful comments, you can ask your comment is useful for other developers. As time goes on, you will have learned how to be a friendly note.

To review other people's comments

In the code review, we tend to ignore the view notes. Don't be afraid to ask for more notes, you should be questioning. If everyone can form good habits of writing comments, then the world will be more beautiful.

Summary

Comments are an important part of the development process, but we should not comment in order to comment. Comments should be useful, simple, should be a complement to the code. Comments should not be used to explain the code line-by-line, on the contrary, it should be used to explain the business logic, reasoning, and inspiration for the future.