Summary sharing of PHP comment syntax specifications and naming conventions

In this article, we will share with you the PHP comment syntax specifications and naming specifications. We know that comments are very important in the process of writing code. Good comments can make your code easier to read. You must pay attention to it when writing code. Annotation specifications. Hope this article can help everyone.

HP Comment Specification

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

"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 standards."

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 name
* @abstract declares a variable/class/method
* @access specifies the access rights of this variable, class, function/method
* @author the 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 indicates the global variable referenced in this function
* @include indicates the information of the included file
* @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 description variables/properties.
* @version defines 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: Several common comment methods in php:

1. File comments, introducing the file name, function and 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 functions, 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 that the more comments, the better good.

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 + underscore for directories
Class libraries and function files are uniformly suffixed with .php
The file names of classes are 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) , other files are named in lowercase + underline
The class name and the class file name are consistent, and uniformly uses camel case (the first letter is capitalized)

2. Functions and classes, attribute naming

Class Naming uses camel case (the first letter is capitalized), such as User, UserType, and no suffix is ​​required by default. For example, UserController should be directly named User
Use lowercase letters and underscores (starting with a lowercase letter) to name functions, such as get_client_ip
Method naming uses camel case (the first letter is 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.Constant 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 fields

Data Tables and fields are named in lowercase and underlined, and field names should 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.

Related recommendations:

phpHow to remove all comments from web files

Details of writing methods and comments in JavaScript Introducing the standard usage of

html, css and js comments

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