PHP Comment Syntax specification and naming specification summary sharing

In this article we will share the PHP comment syntax and naming conventions, and we know that annotations are very important in writing code, that good annotations make your code easier to read, and that you pay attention to the specification of annotations when you write code. I hope this article can help everyone.

HP Annotation Specification

Annotations are important in the process of writing code, and good annotations make your code easier to read, so be sure to note the specification when writing code.

"PHP is a simple and easy to get started language, and it's possible for beginners to print out a 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 be a programmer, then you have to follow a set of program writing specifications, "

We often write functions, but these functions can only be understood by themselves, and even after a period of time they do not know what they wrote, then how to do? The best way of course is to add comments to your own code.

We may be familiar with a lot of comments written in C pear php comments and so on, but we use the main still # and/**/.

#是一种简短的注释方法. Maybe you'll use it to annotate a variable, or call a method. /**/we're probably still using it to comment out a large piece of code, but how do you use it to annotate a function with a standard?

/**
* @name Name
* @abstract declaration variable/class/method
* @access indicates access to this variable, class, function/method
* @author function Author's name and email address

* @category Organization Packages
* @copyright Specify Copyright information
* @const Specified constants
* @deprecate indicate information that is not recommended or discarded
* @example Example
* @exclude indicates that the current comment will not be analyzed and does not appear in the text block
* @final indicates that this is a final class, method, property, prohibit derivation, modification.
* @global indicate the global variables referenced in this function
* @include indicate the information contained in the file
* @link define an online connection
* @module define the module information for attribution
* @modulegroup module groups that define attribution
* @package Define the information of the packages that belong to
* @param define parameter information for a function or method
* @return Define the return information of a function or method
* @see define functions, variables to be referenced, and add the corresponding super connections.
* @since indicates which version of the API function or method was introduced from
* @static indicates that variables, classes, functions are static.
* @throws indicates an error that could be thrown by this function, which is extremely occurring
* @todo indicate areas that should be improved or not implemented
* @var Define description variables/properties.
* @version define version information
*/

The information in the comments is comprehensive, there may be a lot of things we don't use, and the red ones are often used by us.

Example: Several common annotation methods in PHP:

1. Document comments, description of file name, function and author version number and other information

/*** file name Brief Introduction * * Document function * @author Author * @version version number * @date 2020-02-02*/

File Header Template

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

2. Class comment, class name and introduction

Introduction to/*** Class * * Class details (optional) * @author author * @version version number * @date 2020-02-02*/

/** * Class Description * * Class details (optional). ）。 * @author     richard<e421083458@163.com> * @since 1.0 * * *     class Test  {}

3. Function comment, function, parameter description and return type

Description of the meaning of the/*** function * * @access public * @author author * @param mixed $arg 1 Parameter one description * @param mixed $arg 2 parameter two description * @return array return type * @d Ate 2020-02-02*/

Function Header Comment

Description of/** * SOME_FUNC * Function * * * @access public * @param mixed $arg 1 parameter one * @param mixed $arg 2 parameter II * @param mixed $mixed This is a mixed type * @since 1.0 * @return Array */Public function thisisfunction ($string, $integer, $mixed) {return array ();}

Program code comments

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

2. A number of statements as a logical block of code, the comment of this block can use the/* */method.

3. Specific comments to a statement, you can use the end of line Comment://.

/* Generate configuration files, data files. */  $this->setconfig (); $this->createconfigfile ();//Create configuration file $this->clearcache ();     Clear Cache file $this->createdatafiles ();  Generate Data Files $this->prepareproxys (); $this->restart ();

PHP Naming conventions

1. Directories and files

Table of contents using lowercase + underline
Class Library, function file unification with. php as suffix
The file name of the class is defined as a namespace, and the path of the namespace is consistent with the path of the class library file
Class files are named with the Hump method (capitalized), and other files are named with lowercase + underscores
The class name and class file name are consistent, using the Camel Hump method (first letter capitalization)

2. Functions and classes, property naming

The name of the class uses the Hump method (capitalized), such as user, usertype, by default does not need to add a suffix, for example, Usercontroller should be named directly as user
The name of the function uses lowercase letters and underscores (the beginning of lowercase letters), such as Get_client_ip
The name of the method uses the Hump method (the first letter lowercase), such as GetUserName (if the method has a return value, then it is customary to use the initial lowercase attribute type, such as s (String), I (int), F (float), B (Boolean), A (array), etc.)
The name of the property uses the Hump method (the first letter lowercase), such as TableName, instance (which is now customary to use the first letter in lowercase attribute types, such as s (String), I (int), F (float), B (Boolean), A (array), etc.)
A function or method that starts with a double underscore "__" as a magic method, 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. Data Form box fields

Data tables 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 the User_name field, and it is not recommended to use hump and Chinese as the data table fields.