Writing Effective PHP Comments

Comments cannot be careless because they want to explain the reasons for the existence of the code rather than the functions, such as compatibility with old interfaces or third-party restrictions, otherwise people who read the code can only rely on guessing. The areas that must be commented include complex conditional judgments, special error handling logic, and temporary bypass restrictions. A more practical way to write comments is to select single-line comments or block comments based on the scene. Use document block comments to explain parameters and return values at the beginning of functions, classes, and files, and keep comments updated. For complex logic, you can add a line to the previous one to summarize the overall intention. At the same time, do not use comments to seal code, but use version control tools.

Writing PHP comments is actually quite important, but many people don’t do it properly. Comments are not just written just a few sentences. The key is to help others (or yourself in the future) understand the code faster.

Why can't comments be sloppy?

When many novices write comments, they like to write ambiguous content like "this function does something", which is actually equivalent to not writing it. A good comment should explain why this code exists, not what it is doing . for example:

• This logic is for compatibility with old versions of interfaces
• A certain parameter needs to be handled specifically because of the limitations of third-party libraries

If this information is not written out, people who read the code can only guess.

Where must I add comments?

Some code blocks are recommended to add comments even if they look very clear, such as:

• Complex conditional judgment, especially when nesting multi-layer if
• Special error handling logic
• Limits that need to be temporarily bypassed (for example, a patch is applied)

For example, if you have a piece of code that processes time format conversion, just looking at the code may know that it is converting formats, but don't know why you must use strtotime() instead of directly DateTime object. At this time, a comment can save a lot of doubts.

How to write comments more practical?

There are two commonly used annotation methods in PHP: single-line comment // and block comment /* */ . Recommended selection based on the scene:

• Use a brief description //
• Functions, classes, and files are commented with document blocks at the beginning, such as:

 /**
 * Process user login logic, including third-party verification process*
 * @param string $username Username * @param string $password Password * @return bool Login is successful*/

Some other tips:

• Don't use comments to "seal" large pieces of code, use version control tools instead
• Keep comments updated, don't let old comments mislead people
• If the logic is complicated, you can add a line of comments to summarize the overall intention

Last point: Don't be afraid to write a few more sentences

Sometimes you will think, "Is this code not obvious?" But when you come back to see it in a few months, you may have to think about it for a long time. Instead of regretting it afterwards, it is better to spend a few more seconds writing it out. Especially for some "pit points" or "non-standard practices", even if you write one or two more sentences, it will be very helpful to later generations.

Basically, that's all. Comments seem small, but it's really a waste of things if you can't do it well.

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