PHP Advanced Programming (1)-Coding specification and document writing

PHP Advanced Programming Learning Note 20140612

An important part of software development is document writing. He can help future program maintainers and users understand your ideas in development. It also makes it easy to re-view your code later. The document also plays an important role in interacting with objects well without knowing the details of the objects to be accessed. There are a number of mature industry standard formats for documenting documents, and complying with these industry standards will help create easy-to-read delegates and make it possible to automate the generation of manuals.

Coding specifications

Coding specifications There may be many developers who have their own views and opinions, and everyone is different. In fact, as long as the team members to agree, follow the same standard is good.

The PHP community is blossoming and has a large library of libraries, frameworks, and components. PHP developers often use several external libraries in their own projects, so it is important that PHP code follow or approach the same code style as possible, allowing developers to easily integrate multiple codebase into their own projects. The Framework interoperability group, or PHP Standard Group, publishes a range of recommended styles. Some of them are about code style, namely Psr-0,psr-1,psr-2 and PSR-4. Typically, your PHP code should follow one or more of these criteria, so that other developers can easily read and use your code. These standards add new rules to the previous standard, so using PSR-1 requires that you follow PSR-0, but you can not follow PSR-2.

• Read PSR-0
• Read PSR-1
• Read PSR-2
• Read PSR-4
• Read about PEAR Coding standards
• Read about Zend Coding standards
• Read about Symfony Coding standards

Document authoring-Types of annotations

The three types of annotation methods commonly used in PHP are one way to increase the readability and maintainability of the program, rather than the only way. Readability and maintainability are mostly in code naming, and project organization is improved.

// This is a single-line comment type /* This is a multiline comment type the second line comment */ /* */

The first kind of comment can be said to be a person, generally used to compare short notes. The second type is used in code that requires a lot of comment. The third type of comment, called a document comment, can be interpreted and placed in a manual in a fixed format. The types of annotations mainly include: class annotations, attribute annotations, method annotations, variable annotations, key algorithms, important code implementations, and so on. All of these pieces are woven together, making it possible for people to know exactly what you did in the future and why.

Document Writing-Grammar parsing

The conversion process from programming language to executable code is called grammatical parsing. When the grammar parser encounters a normal comment, it recognizes it and ignores it, and cleans up the data in the comment, so the general comment cannot be moved to the metadata.

Meta data

The metadata is defined as data about data. is a widespread phenomenon, in many areas there are specific definitions and applications. It is defined as: Data describing data, descriptive information about the data and information resources. PHP contains the metadata for most programming elements. However, you may need to embed more metadata, because metadata is useful for automating document generation. This functionality can be simulated by parsing the document annotations. If you create a document comment that follows a specific format, the parser can automatically convert the annotation to a meaningful document.

PHPDoc

PHPDoc is a solution for maintaining PHP documents. It provides a structure for document comments that allows the parser to parse them in a consistent manner. With Phpdoc, you can create manuals from embedded documents. As with all document annotations, PHPDOC requirements must begin with the/** comment declaration. The special thing about PHPDoc is the label. The label is denoted by the @ and a predefined identifier. For more information on Phpdoc, please refer to http://www.phpdoc.org/docs/latest/index.html

Notes for the PHPDOC specification

The comment block must start with "/**" and End With "*/".

Each line between the start comment and the end begins with an asterisk (*).

Labels must be written at the beginning of at-sign (@) on a new line, followed by a

There are several tags that support or require types to represent the types of values that are contained in related elements. An example of this is the "param tag to determine a method or function Parameters of type .

Here are a full listing:

string: A piece of text of an unspecified length.
int or integer: A whole number, or be either positive or negative.
float: A real, or decimal, number that may either positive or negative.
bool or boolean: A variable that can is only contain ' true ' or ' false '.
Array: A collection of variables of unknown type. It is possible to specify the types of the array members and see the chapter on arrays for more information.
resource: A file handler or other system resource as described in the PHP manual.
null: The value contained, or returned, is literally null. This type was not confused with void, which is the total absence of a variable or value (usually used with the @retur n tag).
callable: A function or method so can be passed by A variable, see the PHP Manual for more Informati On Callables.

All tags for phpdoc are listed below:

@api	@author	@category	@copyright	@deprecated	@example
@filesource	@global	@ignore	@internal	@license	@link
@method	@package	@param	@property	@property-read	@property-write
@return	@see	@since	@source	@subpackage	@throws
@todo	@uses	@var	@version