PHP 進階編程(1)_PHP教程

PHP 進階程式設計學習筆記20140612

軟體開發中的一個重要環節就是文檔編寫。他可以協助未來的程式維護人員和使用者理解你在開發時的思路。也便於日後重新查看代碼時不至於無從下手。文檔還有一個重要的作用，在不用瞭解要訪問對象的細節情況下也能很好的在對象之間進行互動。文檔的編寫有一些成熟的行業標準格式，遵守這些行業標準將有助於建立易於閱讀的代表，並使自動產生手冊成為可能。

編碼規範

編碼規範可能很多開發人員都有各自的觀點也意見，且大家不盡相同。其實只要團隊成員之間達成一致，遵循同一個標準就好。

PHP社區百花齊放，擁有大量的函數庫、架構和組件。PHP開發人員通常會在自己的項目中使用若干個外部庫，因而PHP代碼遵循或盡量接近 同一個代碼風格就非常重要，可以讓開發人員方便地把多個程式碼程式庫整合在自己的項目中。架構互操作組(即PHP標準組)發布了一系列推薦風格。其中有部分是關於代碼風格的，即PSR-0，PSR-1，PSR-2和PSR-4。通常情況下，你的PHP代碼應該遵循其中一項或多項標準，從而其他開發人員可以方便地閱讀和使用你的代碼。這些標準都是在前一個標準 上附加新的規則，所以使用PSR-1就同時要求遵循PSR-0，但可以不遵循PSR-2。

• 閱讀PSR-0
• 閱讀PSR-1
• 閱讀PSR-2
• 閱讀PSR-4
• Read about PEAR Coding Standards
• Read about Zend Coding Standards
• Read about Symfony Coding Standards

文檔編寫 - 注釋的類型

PHP 中常用的三種注釋方法，注釋是增加程式可讀性、可維護性的一種方法，而不是唯一方法。可讀性和可維護性主要還是在代碼命名，項目組織處提高。

//這是一個單行注釋類型/* 這是一個多行注釋類型 第二行注釋*//** * * 這種形式的注釋被稱為 文檔注釋 */

第一種注釋可以說是給人看的，一般用來比較簡短的注釋。第二種，則用在需要大量注釋的代碼中。第三種注釋被稱為文檔注釋，可以被及其解釋，且能以固定的格式放到手冊中去。注釋的種類主要包括：類的注釋，屬性注釋、方法注釋、變數注釋以及關鍵演算法、重要代碼實現等。所有的這些部分編織在一起，使得人們在以後的時間裡能夠準確的知道你幹了什麼，為什麼這麼做。

文檔編寫 - 文法解析

從程式設計語言到可執行代碼的轉換過程叫做文法解析。當文法解析器遇到一個正常的注釋時，它會識別它並忽略它，並且清理掉注釋中的資料，因此一般的注釋是無法遷入中繼資料的。

中繼資料

中繼資料的定義是 data about data 。是一種廣泛存在的現象，在許多領域有具體的定義和應用。其被定義為：描述資料的資料，對資料及資訊資源的描述性資訊。PHP包含了大多數編程元素的中繼資料。然而，你可能需要嵌入更多的中繼資料，因為中繼資料在自動產生文檔方面非常有用。這種功能可以通過文檔注釋的解析來類比。如果建立遵循特定格式的文檔注釋，解析器可以將注釋自動轉換稱為有意義的文檔。

PHPDoc

PHPDoc 是用於維護PHP文檔的解決方案。其為文檔注釋定一輛一種結構，允許解析器以一致的方式解析它們。有了PHPDoc就可以從嵌入文檔中建立手冊了。 和所有文檔注釋一樣，PHPDoc 要求必須以/**注釋聲明開始。PHPDoc 的特殊之處在於標籤。 標籤由@開始加上一個預定義的標示符表示。關於PHPDoc的更多資訊請參考 http://www.phpdoc.org/docs/latest/index.html

PHPDoc 規範的注釋

註解區塊必須以“/**”開始，以“*/”結束。

開始注釋和結束之間的每行都以星號（*）開始。

標籤必須以 at-sign (@) 開頭在新行書寫，接著寫標

有幾個標籤支援或需要用類型來表示包含在相關元素的值的類型。這方面的一個例子是“param標記，以確定一個方法或函數參數的類型。

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 軟體開發中的一個重要環節就是文檔編寫。他可以協助未來的程式維護人員和使用者理解你在開發時的思路...

