PHP Advanced Programming (1)_PHP Tutorial

PHP Advanced Programming Study Notes 20140612

An important part of software development is document writing. It can help future program maintainers and users understand your thinking during development. It also makes it easier to review the code in the future without knowing where to start. Documents also play an important role in enabling interactions between objects without knowing the details of the objects to be accessed. There are some well-established industry standard formats for document writing, and adhering to these industry standards will help create easy-to-read representations and make it possible to automatically generate manuals.

Coding specifications

Coding standards may have many developers having their own views and opinions, and everyone is different. In fact, as long as team members reach an agreement and follow the same standards, it will be fine.

The PHP community is flourishing, with a large number of function libraries, frameworks and components. PHP developers usually use several external libraries in their own projects, so it is very important for PHP code to follow or be as close as possible to the same code style, which allows developers to easily integrate multiple code libraries into their own projects. The Framework Interop Group (ie the PHP Standards Group) has published a series of recommended styles. Some of them are about coding styles, namely PSR-0, PSR-1, PSR-2 and PSR-4. Typically, your PHP code should follow one or more of these standards 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 compliance with PSR-0, but does not require compliance with 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

Documentation Writing - Types of Comments

There are three commonly used comment methods in PHP. Comments are a way to increase the readability and maintainability of a program, not the only way. Readability and maintainability are mainly improved in code naming and project organization.

<span>//</span><span>这是一个单行注释类型</span>

<span>/*</span><span>
 这是一个多行注释类型
 第二行注释
</span><span>*/</span>

<span>/*</span><span>*
 *
 * 这种形式的注释被称为 文档注释
 </span><span>*/</span>

The first type of comments can be said to be for people to read, and are generally used for shorter comments. The second type, is used in code that requires a lot of comments. The third type of comments, called documentation comments, can be interpreted and placed in a manual in a fixed format. The types of comments mainly include: class comments, attribute comments, method comments, variable comments, key algorithms, important code implementations, etc. All of these pieces are woven together so that people at a later date will know exactly what you did and why you did it.

Document Writing - Grammar Analysis

The conversion process from programming language to executable code is called grammar parsing. When the grammar parser encounters a normal comment, it will recognize it and ignore it, and clean up the data in the comment, so general comments cannot import metadata.

Metadata

The definition of metadata is data about data. It is a widespread phenomenon with specific definitions and applications in many fields. It is defined as: Data describing data, descriptive information about data and information resources. PHP contains metadata for most programming elements. However, you may want to embed more metadata, as metadata is very useful in automatically generating documents. This functionality can be simulated through the parsing of documentation comments. If you create document comments that follow a specific format, the parser can automatically convert the comments into meaningful documents.

PHPDoc

PHPDoc is a solution for maintaining PHP documentation. It defines a structure for documentation comments, allowing parsers to parse them in a consistent way. With PHPDoc you can create manuals from embedded documents. Like all documentation comments, PHPDoc requirements must end with /**Annotation declaration begins. What's special about PHPDoc is the tags. Tags are represented by starting with @ followed by a predefined identifier. For more information about PHPDoc, please refer to http://www.phpdoc.org/docs/latest/index.html

Annotations for the PHPDoc specification

The comment block must start with "/**" and end with "*/".

Each line between the opening comment and the closing comment begins with an asterisk (*).

The

tag must be written on a new line starting with at-sign (@), followed by the sign

Several tags support or require a type to represent the type of the value contained in the associated element. An example of this is "param tag , to identify aMethod or functionType of parameter.

Here is a full listing：

string：A piece of text of an unspecified length.
int or integer：A whole number that may be either positive or negative.
float：A real, or decimal, number that may be either positive or negative.
bool or boolean：A variable that can only contain the state ‘true’ or ‘false’.
array：A collection of variables of unknown type. It is possible to specify the types of array members, 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 is not to be confused with void, which is the total absence of a variable or value (usually used with the @return tag).
callable：A function or method that can be passed by a variable, see the PHP manual for more information on callables.

下面列出PHPDoc的全部标签：

@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

 

 

http://www.bkjia.com/PHPjc/802363.htmlwww.bkjia.comtruehttp://www.bkjia.com/PHPjc/802363.htmlTechArticlePHP 高级程序设计学习笔记20140612 软件开发中的一个重要环节就是文档编写。他可以帮助未来的程序维护人员和使用者理解你在开发时的思路...