Detailed explanation of PHP comment syntax specifications and naming conventions

Comments are very important in the process of writing code. Good comments can make your code easier to read. When writing code, you must pay attention to the specifications of comments. Here is a summary for everyone. Friends who need it can refer to it. Down.

HP Comment Specification

Comments are very important in the process of writing code. Good comments can make your code easier to read. Be sure to read it when writing code. Pay attention to the specification of comments.

"PHP is an extremely easy language to get started with. A novice who has just started may be able to use echo to print out a hello world in less than a few minutes! But is he a real programmer? How to do it? What about defining a programmer? If you want to truly become a programmer, you must follow a set of program writing specifications."

We often write some functions, but these functions may only be understood by ourselves, or even It’s been a while since I didn’t recognize what I wrote, so what should I 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 名字
* @abstract 申明变量/类/方法
* @access 指明这个变量、类、函数/方法的存取权限
* @author 函数作者的名字和邮箱地址
* @category 组织packages
* @copyright 指明版权信息
* @const 指明常量
* @deprecate 指明不推荐或者是废弃的信息
* @example 示例
* @exclude 指明当前的注释将不进行分析，不出现在文挡中
* @final 指明这是一个最终的类、方法、属性，禁止派生、修改。
* @global 指明在此函数中引用的全局变量
* @include 指明包含的文件的信息
* @link 定义在线连接
* @module 定义归属的模块信息
* @modulegroup 定义归属的模块组
* @package 定义归属的包的信息
* @param 定义函数或者方法的参数信息
* @return 定义函数或者方法的返回信息
* @see 定义需要参考的函数、变量，并加入相应的超级连接。
* @since 指明该api函数或者方法是从哪个版本开始引入的
* @static 指明变量、类、函数是静态的。
* @throws 指明此函数可能抛出的错误异常,极其发生的情况
* @todo 指明应该改进或没有实现的地方
* @var 定义说明变量/属性。
* @version 定义版本信息
*/

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

Example: Several common comment methods in php:

1. Comments on the file, introducing the file name, function, author version number and other information

/**
* 文件名简单介绍
* 
* 文件功能
* @author 作者
* @version 版本号
* @date 2020-02-02
*/

File header Template

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

2. Class comments, class name and introduction

/**
* 类的介绍
* 
* 类的详细介绍（可选）
* @author 作者
* @version 版本号
* @date 2020-02-02
*/

/** 
* 类的介绍 
* 
* 类的详细介绍（可选。）。 
* @author     richard<e421083458@163.com> 
* @since     1.0 
*/ 
class Test  
{ 
}

3. Function comments, function function, parameter introduction and return type

/**
* 函数的含义说明
* 
* @access public 
* @author 作者
* @param mixed $arg1 参数一的说明 
* @param mixed $arg2 参数二的说明
* @return array 返回类型
* @date 2020-02-02
*/

Function header Comments

/** 
* 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();}

Program code comments

1. The principle of comments is to explain the problem clearly, not more is 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();

PHP naming convention

1. Directories and files

Use lowercase underscores for directories
Class libraries, function files are uniformly .php The file names of classes with the suffix
are all defined in namespaces, and the path of the namespace is consistent with the path of the class library file
Class files are named using camel case (the first letter is capitalized), and other files are named with lowercase underscores
The class name and class file name should be consistent, and uniformly use camel case (the first letter is capitalized)

2. Function and class, attribute naming

The class name should use camel case (the first letter is capitalized), for example User, UserType, do not need to add a suffix by default. For example, UserController should be named directly as User
. Use lowercase letters and underscores (starting with a lowercase letter) when naming functions. For example, use camel case (first letter) when naming the get_client_ip
method. Lowercase), such as getUserName (if the method has a return value, it is currently customary to use lowercase attribute types with the first letter, such as s (string), i (int), f (float), b (boolean), a (array) etc.)
Use camel case naming of attributes (the first letter is lowercase), such as tableName, instance (it is currently customary to use lowercase attribute types with the first letter, such as s (string), i (int), f (float), b(boolean), a(array), etc.)
Functions or methods starting with double underscore "__" are used as magic methods, such as __call and __autoload

3. Constants and configuration

Constant names are named with uppercase letters and underscores, such as APP_PATH and THINK_PATH
Configuration parameters are named with lowercase letters and underscores, such as url_route_on and url_convert

4. Data table box field

Data table and fields are named in lowercase and underlined, and note that field names do not start with an underscore, such as the think_user table and user_name field. It is not recommended to use camel case and Chinese as data table field names.

The above is the detailed content of Detailed explanation of PHP comment syntax specifications and naming conventions. For more information, please follow other related articles on the PHP Chinese website!