Writing good comments can improve code readability and collaboration efficiency. PHP supports three annotation methods: //, # and //. Among them, // is the most commonly used, suitable for simple internal descriptions of functions, # is often used next to configuration items, // is suitable for module descriptions or block code blocks; when writing functions and classes, DocBlock document annotations should be used, including function descriptions, parameter descriptions and return values, to help the IDE prompt information and generate documents; comments should explain "why" rather than "what was done", avoid meaningless descriptions, and focus on explaining complex logic and key intentions.

Writing good comments is a very important part of programming, especially for beginners with PHP. Good comments can make it easier for you and others to understand code logic, reduce the probability of errors, and improve collaboration efficiency. This article will talk about some basic practices and practical suggestions for PHP annotations.

Single-line comment vs Multi-line comment: How to choose?

PHP supports three common annotation methods: // , # and /* */ . The first two are single-line comments, which are suitable for brief explanations of a certain line of code; the third is multi-line comments, which are suitable for writing a large paragraph of explanation or temporarily blocking a piece of code.

• // It is the most commonly used, especially when making some simple explanations inside the function
• # less, but the effect is the same. Some people are used to using it next to the configuration item
• /* ... */ More suitable for writing module descriptions and temporary blocking of code blocks

For example:

 // Get user information $user = getUserInfo($id);

/*
  Here is a piece of debugging code that can be temporarily retained to facilitate subsequent viewing process*/

It is recommended to choose the appropriate annotation method according to the scene, and do not mix too many types to maintain consistency.

Comments to functions and classes: Don't ignore DocBlock

A point that novices often overlook is adding document comments (DocBlocks) to functions and classes. Although it is not necessary, it can help the IDE automatically complete and generate documents, and also facilitate others to quickly understand your code structure.

A standard DocBlock includes function description, parameter description, return value, etc.:

 /**
 * Get basic user information*
 * @param int $userId User ID
 * @return array|false Returns the user information array, fails to return false
 */
function getUserInfo($userId) {
    // ...
}

Pay attention to writing:

• The description is concise and clear, without long-winded
• The parameter name and type must be written correctly
• If the function may return multiple types, remember to write them

The IDE will recognize these comments and prompt for more accurate information, which is very helpful for later maintenance.

What to write about the comments? Don't write nonsense

Many people tend to fall into the misunderstanding of "writing nonsense" when writing comments at the beginning, such as:

 $i = 0; // Initialize variable i

This kind of comment is actually meaningless. A truly useful comment should explain "why" rather than "what was done".

A better way to write it is:

 $i = 0; // Counter is used to prevent infinite loops

Or when encountering complex logic:

 //Judge whether you have permission to access if ($role === 'admin' || in_array($role, $allowedRoles)) {
    // ...
}

The point is to make the logic clear, especially those that don’t seem very intuitive. This way, others can understand your intentions faster when reading the code.

Basically that's it. The more comments, the better, nor are they dispensable. The key is to write it useful, clear and easy to understand. When I first started writing PHP, I would develop good habits, and I wouldn't be confused when I read the code I wrote in the future.

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