Effective PHP Commenting

The key to writing PHP comments is clear, useful and concise. 1. Comments should explain the intention behind the code rather than just describing the code itself, such as explaining the logical purpose of complex conditional judgments; 2. Add comments to key scenarios such as magic values, old code compatibility, API interfaces, etc. to improve readability; 3. Avoid duplicate code content, keep it concise and specific, and use standard formats such as PHPDoc; 4. Comments should be updated synchronously with the code to ensure accuracy. Good comments should be thought from the perspective of others, reduce the cost of understanding, and become a code understanding navigation device.

Writing PHP comments is not difficult, but it is actually quite particular to write them clearly, usefully and without being verbose. Many people write comments either too simple, such as just writing "what does this function do?" or it is too complicated, and they can't see the key points clearly. A truly effective PHP comment should make people see the intention at a glance and reduce the cost of understanding.

Why do you need to write the comments clearly?

You may think that the code can speak by itself, but often, variable names and function names do not fully express the intention behind the logic. Especially when the business logic is more complicated, without comments is like missing road signs, and others (even yourself) are prone to getting lost when they come back to see the code.

For example:

 if ($user->role !== 'admin' && $user->status !== 'active') {
    return false;
}

This code looks simple, but if you add a comment:

 // This operation cannot be performed by non-administrators or unactivated users

Then the meaning of the whole judgment is much clearer.

Therefore, the role of annotation is not only to indicate what was done, but more importantly to explain why it is done .

Where are the most worthy of commenting?

Not every line of code needs comments, but the following scenarios are recommended:

• Complex conditional judgment : triple or more if/else or nested logic.
• Where the magic value comes from unknown sources : For example, $type = 3 , if 3 is a certain status code, it is best to indicate the meaning.
• Strange but must be retained old code : Sometimes, in order to be compatible with old systems, you have to write some inelegant code, and the comments can help you "disclaim your liability".
• API interface parameter description : Especially the return value structure, it is very critical to the caller.

for example:

 /**
 * Obtain user information*
 * @param int $userId User ID
 * @return array contains name, email, role fields*/
function getUserInfo($userId) {
    // ...
}

This kind of documentary annotation can also be automatically prompted in the IDE and is very practical.

How to write comments so that they won’t become “nonsense”?

There are also ways to write comments, and you can refer to the following points:

• Avoid duplicate code content : do not write comments like "Set title to $title" unless there is a special reason.
• Keep it simple but specific : just explain the purpose, and you don’t need to make a long speech.
• Use standard formats : Structured annotations like PHPDoc are more suitable for teamwork.
• Update comments in time : if the code is changed, the comments must be updated simultaneously, otherwise it will be worse than not.

A few tips:

• After writing a paragraph of logic, look back to see if you need to add comments.
• When looking at other people's code, pay attention to what makes you stuck, and those are the places that should be added.
• If you read a piece of code twice before you understand, then the comments you write now should be understood by others.

Basically that's it

The core of effective annotations is to think from the perspective of others. It is not a repeater for code, but a navigator for helping understand. Don't be afraid to write comments, but avoid writing randomly. Writing well can not only help others, but also help you quickly find your ideas in the future.

The above is the detailed content of Effective PHP Commenting. For more information, please follow other related articles on the PHP Chinese website!