Go homepage(回首页) Upload pictures (上传图片) Write articles (发文字帖)
The author:(作者)qqpublished in(发表于) 2015/6/6 7:30:10 Code comment： note the “5 should not be 3“
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.
赞