Comments are an important part of Clean Code because they explain the intent behind the code rather than repeating the code. Good comments should appear in complex logic, non-intuitive conditional judgments, public API definitions, and to-dos; avoid meaningless descriptions, focus on explaining "why" and keeping them updated while using full sentence expressions. PHP supports three annotation formats: single line, multi-line and docblock. Docblock is not only beautiful, but can also be recognized by the IDE to improve team collaboration efficiency. Following framework specifications also contribute to project unity. Writing comments is not to make up the number of words, but to improve the readability and maintenance of the code and save future understanding costs.

In addition to clear logic and reasonable structure, writing PHP code is also an easy to ignore but very critical part. Clean code and appropriate comments can make it easier for others and even in the future to understand and maintain.

Why are comments part of Clean Code?

Many people think that "clean code" means good variable naming, single function responsibilities, and clear structure. This is true, but the value of comments is ignored. A good comment is not about repeating the code, but about explaining the intention behind the code. for example:

• Why does this function handle boundary situations like this?
• Is there any business reason behind a seemingly strange logic?
• What are the design patterns of this class for?

If this information is only based on the code itself, it is difficult to express clearly, and then comments are needed to fill in.

Where should the comment be written?

Not every line of code needs comments, which will interfere with reading. Focus on the following positions:

• Complex logic or algorithm : For example, a sorting logic uses a specific optimization strategy.
• Non-intuitive judgment conditions : For example, if ($value % 3 === 0 && $value > 10) , you can add a sentence to explain what business meaning this condition represents.
• Public API or interface definition : Use docblock to specify parameters, return values, and possible exceptions to be thrown.
• To-do or technical debt tag : like // TODO: 需要優(yōu)化性能or // FIXME: 臨時(shí)方案.

 /**
 * Calculate user level based on cumulative points and active days*
 * @param int $points Total points* @param int $activeDays Number of active days in the last 90 days* @return string User level (bronze/silver/gold/platinum)
 */
function calculateUserLevel(int $points, int $activeDays): string {
    // ...
}

How to write comments so that they won’t turn into garbage?

Many comments end up becoming "scrap", such as "Set username", but the result is just $this->username = $username; . This is not necessary. A truly useful comment should do the following:

• Don't repeat the code : don't write meaningless comments like "Set ID".
• Explain "why" instead of "what was done" : for example, "The cast to an integer is for compatibility with the old data format."
• Keep updated : the code has been changed and the comments must be synchronized, otherwise it will be more troublesome to mislead others.
• Use full sentences : Although not writing a paper, fluent sentences are helpful for understanding.

Don't ignore the IDE-friendly annotation format

There are three common annotation styles in PHP:

• Single line comment: //
• Multi-line comments: /* ... */
• Docblock: used for classes, methods, properties, etc., usually in the form of /** ... */

The docblock format is not only beautiful, but can also be correctly recognized by the IDE, and automatically prompts parameter types, return values and other information. This is especially important for teamwork.

In addition, if you are using mainstream frameworks such as Laravel or Symfony, they also have certain requirements for the annotation specifications. Following the framework style will make the project more unified.

Basically that's it. Comments are not written to make up the word count, but to improve code readability and maintainability. Don't be afraid to take some time to write it clearly. What you may save may be several times the time in the next few times to "guess" what this code is trying to do.

The above is the detailed content of Clean Code and Comments in PHP. For more information, please follow other related articles on the PHP Chinese website!