Comments and file structure descriptions of the PHP coding specification
- 2020-03-31 20:57:36
- OfStack
File structure
| � � images
| � � the include
| � � parameter
| � � config
| � � function
| � � index
Images store image files. Include is the file to be referenced by the system. Generally, parameter files are stored in parameter, config files are stored in config, and method files such as javascript methods are stored in function
The file name
The name of the folder is generally in English, the length is generally not more than 20 characters, named by lowercase letters. Some common folder names are images, flash, style, scripts, inc, include, link,media, etc. File names are all lowercase combinations of letters, Numbers, and underscores.
Block comments
Block annotations are commonly used to provide descriptions of files, methods, data structures, and algorithms. Block comments are placed at the beginning of each file and before each method. They can also be used elsewhere, such as inside methods. Block comments within functions and methods should have the same indentation format as the code they describe.
There should be a blank line at the beginning of the block comment to separate the block comment from the code, for example:
Block comments can start with /*-, so that indent(1) recognizes it as the start of a code block without rearrangement.
Note: if you don't use indent(1), you don't have to use /*- in your code, or compromise that someone might run indent(1) on your code.
Single-line comments
Short comments can be displayed on a line and have the same level of indentation as the code that follows. If a comment cannot be written in one line, a block comment should be used. A single line comment should be preceded by a blank line. Here is an example of a single line comment in the code:
If (condition) {
.
}
End of annotation
Extremely short comments can be on the same line as the code they describe, but there should be enough white space to separate the code from the comments. If more than one short comment appears in a large piece of code, they should have the same indentation.
Here is an example of a tail comment in the code:
At the end of the line of comments
The comment delimiter "//" allows you to comment out entire lines or portions of a line. It is generally not used for consecutive lines of comment text; However, it can be used to comment out consecutive lines of code. Here are examples of all three styles:
Documentation comments
Documentation comments describe PHP's classes, constructors, methods, and fields. Each document comment is placed in an annotation delimiter, one for each class or member. The comment should precede the declaration:
The class Example {...
Notice that the top-level class is not indented, and its members are indented. The first line (/**) of the document comment that describes the class is indented; Subsequent document comments are indented by 1 space per line (align asterisks lengthwise). A member, including the constructor, whose document comments are indented by four Spaces on the first line, followed by five Spaces on each line.
If you want to give information about a class, variable, or method that is not suitable for documentation, you can use an implementation block comment (see 5.1.1) or a single-line comment that follows the declaration (see 5.1.2). For example, details about a class implementation should be placed in an implementation block comment immediately after the class declaration, rather than in a document comment.
Document comments cannot be placed in the definition block of a method or constructor because the program associates the first declaration after the document comment with it.
| � � images
| � � the include
| � � parameter
| � � config
| � � function
| � � index
Images store image files. Include is the file to be referenced by the system. Generally, parameter files are stored in parameter, config files are stored in config, and method files such as javascript methods are stored in function
The file name
The name of the folder is generally in English, the length is generally not more than 20 characters, named by lowercase letters. Some common folder names are images, flash, style, scripts, inc, include, link,media, etc. File names are all lowercase combinations of letters, Numbers, and underscores.
Block comments
Block annotations are commonly used to provide descriptions of files, methods, data structures, and algorithms. Block comments are placed at the beginning of each file and before each method. They can also be used elsewhere, such as inside methods. Block comments within functions and methods should have the same indentation format as the code they describe.
There should be a blank line at the beginning of the block comment to separate the block comment from the code, for example:
Block comments can start with /*-, so that indent(1) recognizes it as the start of a code block without rearrangement.
Note: if you don't use indent(1), you don't have to use /*- in your code, or compromise that someone might run indent(1) on your code.
Single-line comments
Short comments can be displayed on a line and have the same level of indentation as the code that follows. If a comment cannot be written in one line, a block comment should be used. A single line comment should be preceded by a blank line. Here is an example of a single line comment in the code:
If (condition) {
.
}
End of annotation
Extremely short comments can be on the same line as the code they describe, but there should be enough white space to separate the code from the comments. If more than one short comment appears in a large piece of code, they should have the same indentation.
Here is an example of a tail comment in the code:
if ($a == 2) {
return TRUE;
} else {
return isPrime($a);
}
At the end of the line of comments
The comment delimiter "//" allows you to comment out entire lines or portions of a line. It is generally not used for consecutive lines of comment text; However, it can be used to comment out consecutive lines of code. Here are examples of all three styles:
if ($foo > 1) {
//The second use.
...
}
else {
return false; //Explains why the value is returned
}
//if ($bar > 1) {
//
// // Third use
// ...
//}
//else {
// return false;
//}
Documentation comments
Documentation comments describe PHP's classes, constructors, methods, and fields. Each document comment is placed in an annotation delimiter, one for each class or member. The comment should precede the declaration:
The class Example {...
Notice that the top-level class is not indented, and its members are indented. The first line (/**) of the document comment that describes the class is indented; Subsequent document comments are indented by 1 space per line (align asterisks lengthwise). A member, including the constructor, whose document comments are indented by four Spaces on the first line, followed by five Spaces on each line.
If you want to give information about a class, variable, or method that is not suitable for documentation, you can use an implementation block comment (see 5.1.1) or a single-line comment that follows the declaration (see 5.1.2). For example, details about a class implementation should be placed in an implementation block comment immediately after the class declaration, rather than in a document comment.
Document comments cannot be placed in the definition block of a method or constructor because the program associates the first declaration after the document comment with it.