When writing PHP comments well, you should explain the intention rather than repeat the code to avoid invalid or outdated content. 1. Comments need to explain "why" rather than "what was done", such as explaining business logic rather than just describing variable settings; 2. Use DocBlock to comment functions and classes to facilitate the generation of documents and IDE prompts; 3. Single-line comments are used for special circumstances or reminders; 4. Update comments should be used as part of the code modification to avoid misleading content; 5. Use tags such as // TODO: and // FIXME: to improve readability and maintenance.
Writing PHP comments is originally intended to help others (and their future self) understand the code better, but irregular comments can make people more confused. Writing good comments is a trivial matter, but it is also the easiest to be overlooked. Below are some common practices and pit avoidance points in actual development.

Explain "why" in clear language, not "what did"
A good comment is not a duplicate code, but an explanation of the intention. for example:
// Bad: Only the code $discount = $price * 0.9 was repeated; // Good: The logic behind the explanation // Apply 10% discount for early payment $discount = $price * 0.9;
Some developers are accustomed to adding nonsense comments such as "set variables" and "loop arrays" before each line of code, which is actually creating noise. What is really useful is to explain those parts that don’t seem very intuitive, such as business rules, reasons for special handling, etc.

Use more document block comments (DocBlock) and less single-line comments
Functions and classes should use the standard DocBlock comment format, which is helpful for generating documents and IDE prompts. For example:
/** * Calculate total price after applying discount and tax. * * @param float $price Original product price * @param float $taxRate Tax rate in percentage (eg, 8.5) * @return float Final price */ function calculateFinalPrice($price, $taxRate) { // ... }
Single-line comments are more suitable for explaining special circumstances of a certain piece of logic or reminding attention:

// Temporary fix until API returns correct format $data = json_decode($response, true);
Don't let comments expire or expire
This is one of the most common problems. The code has been changed for several rounds, but the comments are still in the original version. In this case, not only does the annotation be useless, it also misleads the reader.
- Update comments should be used as part of modifying the code
- If you are not sure whether a comment is accurate, you can add
// TODO:
mark to remind you to confirm the subsequent confirmation.
Also, don't leave large pieces of old code commented out in the code. If you really need to preserve historical logic, you can check it through the version control tool, and there is no need to pollute the current code structure.
Tips: Make good use of labels to improve readability
You can use some common tags in comments to mark special content, such as:
-
// TODO:
Indicates to-do items -
// FIXME:
indicates a known problem -
// HACK:
indicates temporary workaround
In this way, other developers can quickly identify potential risks or points to be optimized after seeing this.
Basically that's it. Writing comments seems simple, but if you want to write them practically and not overdone, you still have to think more from the perspective of the reader.
The above is the detailed content of PHP Commenting Dos and Don'ts. For more information, please follow other related articles on the PHP Chinese website!

Hot AI Tools

Undress AI Tool
Undress images for free

Undresser.AI Undress
AI-powered app for creating realistic nude photos

AI Clothes Remover
Online AI tool for removing clothes from photos.

Clothoff.io
AI clothes remover

Video Face Swap
Swap faces in any video effortlessly with our completely free AI face swap tool!

Hot Article

Hot Tools

Notepad++7.3.1
Easy-to-use and free code editor

SublimeText3 Chinese version
Chinese version, very easy to use

Zend Studio 13.0.1
Powerful PHP integrated development environment

Dreamweaver CS6
Visual web development tools

SublimeText3 Mac version
God-level code editing software (SublimeText3)

Hot Topics

The method to get the current session ID in PHP is to use the session_id() function, but you must call session_start() to successfully obtain it. 1. Call session_start() to start the session; 2. Use session_id() to read the session ID and output a string similar to abc123def456ghi789; 3. If the return is empty, check whether session_start() is missing, whether the user accesses for the first time, or whether the session is destroyed; 4. The session ID can be used for logging, security verification and cross-request communication, but security needs to be paid attention to. Make sure that the session is correctly enabled and the ID can be obtained successfully.

To extract substrings from PHP strings, you can use the substr() function, which is syntax substr(string$string,int$start,?int$length=null), and if the length is not specified, it will be intercepted to the end; when processing multi-byte characters such as Chinese, you should use the mb_substr() function to avoid garbled code; if you need to intercept the string according to a specific separator, you can use exploit() or combine strpos() and substr() to implement it, such as extracting file name extensions or domain names.

In PHP, the most common method is to split the string into an array using the exploit() function. This function divides the string into multiple parts through the specified delimiter and returns an array. The syntax is exploit(separator, string, limit), where separator is the separator, string is the original string, and limit is an optional parameter to control the maximum number of segments. For example $str="apple,banana,orange";$arr=explode(",",$str); The result is ["apple","bana

std::chrono is used in C to process time, including obtaining the current time, measuring execution time, operation time point and duration, and formatting analysis time. 1. Use std::chrono::system_clock::now() to obtain the current time, which can be converted into a readable string, but the system clock may not be monotonous; 2. Use std::chrono::steady_clock to measure the execution time to ensure monotony, and convert it into milliseconds, seconds and other units through duration_cast; 3. Time point (time_point) and duration (duration) can be interoperable, but attention should be paid to unit compatibility and clock epoch (epoch)

ToaccessenvironmentvariablesinPHP,usegetenv()orthe$_ENVsuperglobal.1.getenv('VAR_NAME')retrievesaspecificvariable.2.$_ENV['VAR_NAME']accessesvariablesifvariables_orderinphp.iniincludes"E".SetvariablesviaCLIwithVAR=valuephpscript.php,inApach

When using PHP preprocessing statements to execute queries with IN clauses, 1. Dynamically generate placeholders according to the length of the array; 2. When using PDO, you can directly pass in the array, and use array_values to ensure continuous indexes; 3. When using mysqli, you need to construct type strings and bind parameters, pay attention to the way of expanding the array and version compatibility; 4. Avoid splicing SQL, processing empty arrays, and ensuring data types match. The specific method is: first use implode and array_fill to generate placeholders, and then bind parameters according to the extended characteristics to safely execute IN queries.

PHPhasthreecommentstyles://,#forsingle-lineand/.../formulti-line.Usecommentstoexplainwhycodeexists,notwhatitdoes.MarkTODO/FIXMEitemsanddisablecodetemporarilyduringdebugging.Avoidover-commentingsimplelogic.Writeconcise,grammaticallycorrectcommentsandu

There are three key ways to avoid the "undefinedindex" error: First, use isset() to check whether the array key exists and ensure that the value is not null, which is suitable for most common scenarios; second, use array_key_exists() to only determine whether the key exists, which is suitable for situations where the key does not exist and the value is null; finally, use the empty merge operator?? (PHP7) to concisely set the default value, which is recommended for modern PHP projects, and pay attention to the spelling of form field names, use extract() carefully, and check the array is not empty before traversing to further avoid risks.
