PHP code comments small details

Code comments are more important than the code itself. Warn new people to develop the habit of writing comments. Otherwise, it will only harm people and avoid self-interest. There are some methods to ensure that the comments you have written in the code are friendly. to sum up, & quot; 5 should be different from 3. & quot;

Code comments are more important than the code itself. Warn new people to develop the habit of writing comments. Otherwise, it will only harm people and avoid self-interest. There are some methods to ensure that the comments you have written in the code are friendly. In summary, they are "5 and 3 don't"
1. do not repeat what the reader already knows (×)

Some method names can be viewed only by code, so there is no need to write comments for functions,

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

II. describe reasoning and history (√)

If the business logic in the code may need to be updated or changed later, leave a comment:

/* The API currently returns an array of itemseven though that will change in an upcoming ticket.Therefore, be sure to change the loop style here so thatwe 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++) {  ...}

3. do not write long comments on the same line (×)

There is nothing that makes it easier for developers to read comments than to drag a horizontal scroll bar. In fact, most developers choose to ignore such annotations, 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}

4. put long comments on the logic and short comments on the back (√)

Note: If it cannot exceed 120 characters, it can be placed next to the code. Otherwise, the comment should be placed directly on 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;    }  };}

5. do not add unnecessary comments for comments (×)

Superfluous comments may cause confusion. In school, the teacher may teach you to add comments to all statements, which will help developers better understand. But this is wrong. If you want to say this, you will immediately give him two ears. The code should be clean and concise, which is beyond doubt. If your code needs to be explained line by line, the most important thing you need to do is refactoring.

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}

6. correct spelling of comments (√)

Do not make excuses for spelling mistakes in code comments. IDE can check the spelling for you. If this function is not available, download the plug-in and start it on your own!
7. exercise more (√)
Practice makes perfect. Try to write some useful comments and ask other developers if your comments are useful. Over time, you will gradually learn how to be a friendly comment.
8. review others' comments (√)
During code review, we tend to ignore viewing comments. Don't be afraid to ask for more comments. you should raise questions. If everyone develops a good habit of writing comments, the world will be better.
9. summary of the essence that must be known for comments

Annotation is a very important part of the development process, but we should not comment for annotation. Annotations should be useful and concise, and should be a supplement to the code. Annotations should not be used to explain code line by line. Instead, they should be used to explain business logic, reasoning, and future inspiration.