Crazy Java Learning Notes (-----------Notes) Note

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

Don't repeat what the reader already knows

It is not helpful for us to have a clear explanation of what the code is doing.

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

To annotate a description of reasoning and history

If the business logic in your code might need to be updated or changed later, you should leave a comment:)

/* The API currently returns an array of Itemseven though that would change in an upcoming ticket. Therefore, be sure to change the loop style here so thatwe properly iterate over a object */var Api_result = {items: ["On E "," "", "" "},    items = api_result.items,    num_items = Items.length;for (var x = 0; x < num_items; + +) {  ...}

Don't write a long note on the same line

Nothing is more heinous than dragging a horizontal scroll bar to read comments. In fact, most developers choose to ignore this type of comment because it is really inconvenient to read.

function person (name) {  this.name = name;  This.first_name = Name.split ("") [0]; This was just a shot in the dark. If We can extract the first name, let's Do it}

To put long annotations on logic, short notes are placed behind

Note If you do not exceed 120 characters, you can put it next to the code. Otherwise, you should put the comment directly above the statement.

if (Person.age <) {  Person.can_drink = false;//drinking Age/  * Fees is given to those under Ly in     some states. *  /Person.has_car_rental_fee = function (state) {    if (state = = = "MI") {      return True;
   }  };}

Do not add unnecessary comments for comments

The superfluous annotations can cause confusion. Maybe in school, the teacher teaches you to annotate all the statements, which will help the developers to understand better. But this is wrong. If you say so, you will give him two big slap right away. There is no doubt that the code should be kept clean and concise. If your code needs to be interpreted on a line-by-row basis, then the most you need to do is refactor.

if (Person.age >=) {  Person.can_drink = true;//a person can drink at  Person.can_smoke = true;//a Pers  On can smoke @  person.can_wed = true;//a person can get married at +  person.can_see_all_movies = true;//A Person can see all movies @  //i hate babies and children and all things pure because I comment too much}

Note to be spelled correctly

Do not make excuses for spelling errors in code comments. The IDE can check spelling for you. If this function is not available, then download the plugin and do it yourself!

Practice more.

Practice makes perfect Try to write some useful comments and ask other developers if your comments are useful. As time goes on, you will slowly learn how to be a friendly annotation.

To review other people's comments

When code is reviewed, we tend to ignore viewing comments. Don't be afraid to ask for more comments, you should ask questions. If everyone has a good habit of writing good notes, then the world will be better.

Summarize

Annotations are a very important part of the development process, but we should not annotate them for comments. Comments should be useful, concise, and should be a complement to the code. Annotations should not be used to interpret code on a line-by-row basis, instead it should be used to explain business logic, reasoning, and implications for the future.

Transfer from http://www.codeceo.com/article/comments-do-and-dont.html

Crazy Java Learning Notes (-----------Notes) Note