Specification guidelines for standard comments in PHP programs

As a language that is relatively easy to get started, many people can easily get started with php, but in the process of learning, you must also abide by PHP's standard comment specifications.

We often write some functions, but these functions may only be understood by ourselves. After a while, we may even not recognize what we wrote. So what should we do? The best way is of course to add comments to your code.

We may be familiar with many ways of writing comments, C pear PHP comments, etc., but the main ones we use are # and /**/.

# is a short comment method. Maybe you will use it to annotate a variable or call a method. /**/. We may still use it to comment out a large section of code. , but how to use it to standardly annotate a function?

/**
* @name Name
* @abstract Declaration of variables/classes/methods
* @access Specifies the access rights of this variable, class, function/method
* @author Name and email address of the function author Address

* @category Organization packages
* @copyright Specify copyright information
* @const Specify constant
* @deprecate Specify deprecated or obsolete information
* @example Example
* @exclude indicates that the current comment will not be analyzed and will not appear in the document
* @final indicates that this is a final class, method, or attribute, and derivation and modification are prohibited.
* @global specifies the global variables referenced in this function
* @include specifies the information of the included files
* @link defines the online connection
* @module defines the attributed module information
* @modulegroup defines the belonging module group
* @package defines the belonging package information
* @param defines the parameter information of the function or method
* @return defines the return information of the function or method
* @see defines the functions and variables that need to be referenced, and adds the corresponding hyperlinks.
* @since indicates which version the api function or method was introduced from.
* @static indicates that variables, classes, and functions are static.
* @throws Indicates the error exceptions that this function may throw, and the circumstances in which they occur
* @todo Indicates areas that should be improved or not implemented
* @var defines variables/attributes.
* @version Define version information
*/

The information in the comments is very comprehensive. There may be a lot that we don’t use. The red parts are the ones we often use.

Example:

File header template

/** 
*这是一个什么文件 
* 
*此文件程序用来做什么的（详细说明，可选。）。 
* @author      richard 
* @version     $Id$ 
* @since        1.0 
*/

Function header comment

/** 
* some_func  
* 函数的含义说明 
* 
* @access public 
* @param mixed $arg1 参数一的说明 
* @param mixed $arg2 参数二的说明 
* @param mixed $mixed 这是一个混合类型 
* @since 1.0 
* @return array 
*/  
public function thisIsFunction($string, $integer, $mixed) {return array();}

Class comments

/** 
* 类的介绍 
* 
* 类的详细介绍（可选。）。 
* @author         richard 
* @since          1.0 
*/  
class Test   
{  
}

Program code comments

1. The principle of comments is to explain the problem clearly, not the more the better.

2. Several statements are used as a logical code block, and the comments of this block can be used in /* */ mode.

3. For comments specific to a certain statement, you can use end-of-line comments: //.

/* 生成配置文件、数据文件。*/  
  
$this->setConfig();  
$this->createConfigFile();  //创建配置文件  
$this->clearCache();         // 清除缓存文件  
$this->createDataFiles();   // 生成数据文件  
$this->prepareProxys();  
$this->restart();

Related recommendations:

Comments in PHP, PHP comments

The above is the detailed content of Specification guidelines for standard comments in PHP programs. For more information, please follow other related articles on the PHP Chinese website!