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!
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
Object-Relational Mapping (ORM) Performance Tuning in PHP
Jul 29, 2025 am 05:00 AM
Avoid N 1 query problems, reduce the number of database queries by loading associated data in advance; 2. Select only the required fields to avoid loading complete entities to save memory and bandwidth; 3. Use cache strategies reasonably, such as Doctrine's secondary cache or Redis cache high-frequency query results; 4. Optimize the entity life cycle and call clear() regularly to free up memory to prevent memory overflow; 5. Ensure that the database index exists and analyze the generated SQL statements to avoid inefficient queries; 6. Disable automatic change tracking in scenarios where changes are not required, and use arrays or lightweight modes to improve performance. Correct use of ORM requires combining SQL monitoring, caching, batch processing and appropriate optimization to ensure application performance while maintaining development efficiency.
Building Immutable Objects in PHP with Readonly Properties
Jul 30, 2025 am 05:40 AM
ReadonlypropertiesinPHP8.2canonlybeassignedonceintheconstructororatdeclarationandcannotbemodifiedafterward,enforcingimmutabilityatthelanguagelevel.2.Toachievedeepimmutability,wrapmutabletypeslikearraysinArrayObjectorusecustomimmutablecollectionssucha
Laravel raw SQL query example
Jul 29, 2025 am 02:59 AM
Laravel supports the use of native SQL queries, but parameter binding should be preferred to ensure safety; 1. Use DB::select() to execute SELECT queries with parameter binding to prevent SQL injection; 2. Use DB::update() to perform UPDATE operations and return the number of rows affected; 3. Use DB::insert() to insert data; 4. Use DB::delete() to delete data; 5. Use DB::statement() to execute SQL statements without result sets such as CREATE, ALTER, etc.; 6. It is recommended to use whereRaw, selectRaw and other methods in QueryBuilder to combine native expressions to improve security
css dark mode toggle example
Jul 30, 2025 am 05:28 AM
First, use JavaScript to obtain the user system preferences and locally stored theme settings, and initialize the page theme; 1. The HTML structure contains a button to trigger topic switching; 2. CSS uses: root to define bright theme variables, .dark-mode class defines dark theme variables, and applies these variables through var(); 3. JavaScript detects prefers-color-scheme and reads localStorage to determine the initial theme; 4. Switch the dark-mode class on the html element when clicking the button, and saves the current state to localStorage; 5. All color changes are accompanied by 0.3 seconds transition animation to enhance the user
go by example generics
Jul 29, 2025 am 04:10 AM
Go generics are supported since 1.18 and are used to write generic code for type-safe. 1. The generic function PrintSlice[Tany](s[]T) can print slices of any type, such as []int or []string. 2. Through type constraint Number limits T to numeric types such as int and float, Sum[TNumber](slice[]T)T safe summation is realized. 3. The generic structure typeBox[Tany]struct{ValueT} can encapsulate any type value and be used with the NewBox[Tany](vT)*Box[T] constructor. 4. Add Set(vT) and Get()T methods to Box[T] without
python json loads example
Jul 29, 2025 am 03:23 AM
json.loads() is used to parse JSON strings into Python data structures. 1. The input must be a string wrapped in double quotes and the boolean value is true/false; 2. Supports automatic conversion of null→None, object→dict, array→list, etc.; 3. It is often used to process JSON strings returned by API. For example, response_string can be directly accessed after parsing by json.loads(). When using it, you must ensure that the JSON format is correct, otherwise an exception will be thrown.
python parse date string example
Jul 30, 2025 am 03:32 AM
Use datetime.strptime() to convert date strings into datetime object. 1. Basic usage: parse "2023-10-05" as datetime object through "%Y-%m-%d"; 2. Supports multiple formats such as "%m/%d/%Y" to parse American dates, "%d/%m/%Y" to parse British dates, "%b%d,%Y%I:%M%p" to parse time with AM/PM; 3. Use dateutil.parser.parse() to automatically infer unknown formats; 4. Use .d
css dropdown menu example
Jul 30, 2025 am 05:36 AM
Yes, a common CSS drop-down menu can be implemented through pure HTML and CSS without JavaScript. 1. Use nested ul and li to build a menu structure; 2. Use the:hover pseudo-class to control the display and hiding of pull-down content; 3. Set position:relative for parent li, and the submenu is positioned using position:absolute; 4. The submenu defaults to display:none, which becomes display:block when hovered; 5. Multi-level pull-down can be achieved through nesting, combined with transition, and add fade-in animations, and adapted to mobile terminals with media queries. The entire solution is simple and does not require JavaScript support, which is suitable for large
