PHP Annotation Syntax Specification and Naming Specification Detailed Explanation

HP annotation specification

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

"php is a very easy language to get started. Beginners may print out an hello world with echo in less than a few minutes! But is he a real programmer? How to define a programmer? If you want to really 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, and even after a period of time, we don't know what we wrote, so what should we do? Of course, the best way is to annotate your own code.

We're probably familiar with a lot of annotations C pear PHP annotations and so on, but we're mostly using # and /**/.

# is a short annotation method. Maybe you will use it to annotate a variable or call a method. /**/We may still be using it to comment out a large piece of code, but how can we use it to comment a function as standard?

/**
* @ name name
* @ abstract declaring variables/classes/methods
* @ access indicates the access permissions for this variable, class, function/method
* The name and email address of the @ author function author

* @ category Organization packages
* @ copyright indicates copyright information
* @ const specifies a constant
* @ deprecate indicates not recommended or discarded information
* @ example sample
* @ exclude indicates that the current comment will not be parsed and will not appear in the document
* @ final indicates that this is a final class, method, property, no derivation, no modification.
* @ global indicates the global variable referenced in this function
* @ include information indicating included files
* @ link defines an online connection
* @ module module information that defines attribution
* @ modulegroup Defines the module group to which to belong
* @ package Defines information about the package to which it belongs
* @ param Defines parameter information for a function or method
* @ return defines the return information of a function or method
* @ see defines the functions and variables that need to be referenced, and adds 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 what happens
* @ todo identifies areas that should be improved or not implemented
* @ var Definition Description Variables/Attributes.
* @ version Definition Version Information
*/

The annotation information is very comprehensive, and there may be many things we don't need. The red part is often used by us.

Example: Several common annotation methods in php:

1. Comments on the file, describing the file name, functions, author version number and other information

/**
*  Brief introduction of file name 
* 
*  File function 
* @author  Author 
* @version  Version number 
* @date 2020-02-02
*/

File header template

/** 
* This is 1 What file  
* 
* What is this file program used to do (detailed description, optional.) .  
* @author   richard<e421083458@163.com> 
* @version   $Id$ 
* @since    1.0 
*/ 

2. Comment, class name and introduction of the class

/**
*  Introduction to the class 
* 
*  Detailed introduction to the class (optional) 
* @author  Author 
* @version  Version number 
* @date 2020-02-02
*/

/** 
*  Introduction to the class  
* 
*  A detailed introduction to the class (optional.) .  
* @author     richard<e421083458@163.com> 
* @since     1.0 
*/ 
class Test  
{ 
} 

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

/**
*  Description of the meaning of function 
* 
* @access public 
* @author  Author 
* @param mixed $arg1  Parameter 1 Description of  
* @param mixed $arg2  Parameter 2 Description of 
* @return array  Return type 
* @date 2020-02-02
*/

Function header comment

/** 
* some_func 
*  Description of the meaning of function  
* 
* @access public 
* @param mixed $arg1  Parameter 1 Description of  
* @param mixed $arg2  Parameter 2 Description of  
* @param mixed $mixed  This is 1 Mixed types  
* @since 1.0 
* @return array 
*/ 
public function thisIsFunction($string, $integer, $mixed) {return array();} 

Program code comment

1. The principle of annotation 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 use /**/ mode.

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

/*  Generate configuration files and data files. */ 
 
$this->setConfig(); 
$this->createConfigFile(); // Create a configuration file  
$this->clearCache();     //  Clear the cache file  
$this->createDataFiles();  //  Generate data files  
$this->prepareProxys(); 
$this->restart(); 

PHP naming convention

1. Contents and documents

Use lowercase + underline for directories
Class library, function file system 1 with. php as suffix
The file name of the class is defined in a namespace, and the path of the namespace and the path of the class library file are 1
Class files are named by hump method (the first letter is uppercase), and other files are named by lowercase + underscore
Class name and class file name are kept as 1, and hump method is adopted in system 1 (first letter is capitalized)

2. Function and class, attribute naming

Classes are named by hump method (initial letters are capitalized), such as User and UserType, and no suffix is needed by default. For example, UserController should be directly named User
Functions are named using lowercase letters and underscores (starting with lowercase letters), such as get_client_ip
Methods are named using hump (lowercase initials), such as getUserName (if the method has a return value, it is customary to use lowercase initials as attribute types, such as s (string), i (int), f (float), b (boolean), a (array), etc.)
Attributes are named by hump method (lowercase initials), such as tableName, instance (at present, it is customary to use lowercase initials as attribute types, such as s (string), i (int), f (float), b (boolean), a (array), etc.)
Functions or methods that begin with a double underscore "__" as magic methods, such as __call and __autoload

3. Constants and Configurations

Constants 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. Datasheet Box Fields

Data tables and fields are named in lowercase with underscores, and note that field names do not start with underscores, such as think_user tables and user_name fields. Hump and Chinese are not recommended for naming data table fields.