理解學習PHP編碼規范之注釋和文件結構,編寫規則的代碼與目錄結構讓大家能快速的熟悉。提高協同工作效率。
文件結構
|――images
|――include
|――parameter
|――config
|――function
|――index
images存放圖片文件,include中是系統是要引用的文件,一般在parameter中存放參數文件,config中存放配置文件,function中存放方法文件,如Javascript的方法等,並按功能模塊的分類,將各功能的類也放入其中
文件名
文件夾命名一般采用英文,長度一般不超過20個字符,命名采用小寫字母。除特殊情況才使用中文拼音,一些常見的文件夾命名如:images(存放圖形文件),Flash(存放Flash文件),style(存放CSS文件),scripts(存放Javascript腳本),inc(存放include文件),link(存放友情鏈接),media(存放多媒體文件)等。文件名稱統一用小寫的英文字母、數字和下劃線的組合。
塊注釋
塊注釋通常用於提供對文件,方法,數據結構和算法的描述。塊注釋被置於每個文件的開始處以及每個方法之前。它們也可以被用於其他地方,比如方法內部。在功能和方法內部的塊注釋應該和它們所描述的代碼具有一樣的縮進格式。
塊注釋之首應該有一個空行,用於把塊注釋和代碼分割開來,比如:
/*
* 這裡是塊注釋
*/
塊注釋可以以/*-開頭,這樣indent(1)就可以將之識別為一個代碼塊的開始,而不會重排它。
/*-
* 如果想被忽略,可是使用特別格式的塊注釋
*
* one
* two
* three
*/
注意:如果你不使用indent(1),就不必在代碼中使用/*-,或為他人可能對你的代碼運行indent(1)作讓步。
單行注釋
短注釋可以顯示在一行內,並與其後的代碼具有一樣的縮進層級。如果一個注釋不能在一行內寫完,就該采用塊注釋。單行注釋之前應該有一個空行。以下是一個代碼中單行注釋的例子:
if (condition) {
/* 以下代碼運行的條件 */
...
}
尾端注釋
極短的注釋可以與它們所要描述的代碼位於同一行,但是應該有足夠的空白來分開代碼和注釋。若有多個短注釋出現於大段代碼中,它們應該具有相同的縮進。
以下是一個代碼中尾端注釋的例子:
行末注釋
注釋界定符"//",可以注釋掉整行或者一行中的一部分。它一般不用於連續多行的注釋文本;然而,它可以用來注釋掉連續多行的代碼段。以下是所有三種風格的例子:
文檔注釋
文檔注釋描述PHP的類、構造器,方法,以及字段(fIEld)。每個文檔注釋都會被置於注釋定界符/**...*/之中,一個注釋對應一個類或成員。該注釋應位於聲明之前:
/**
* 說明這個類的一些 ...
*/
class Example { ...
注意頂層(top-level)的類是不縮進的,而其成員是縮進的。描述類的文檔注釋的第一行(/**)不需縮進;隨後的文檔注釋每行都縮進1格(使星號縱向對齊)。成員,包括構造函數在內,其文檔注釋的第一行縮進4格,隨後每行都縮進5格。
若你想給出有關類、變量或方法的信息,而這些信息又不適合寫在文檔中,則可使用實現塊注釋(見5.1.1)或緊跟在聲明後面的單行注釋(見5.1.2)。例如,有關一個類實現的細節,應放入緊跟在類聲明後面的實現塊注釋中,而不是放在文檔注釋中。
文檔注釋不能放在一個方法或構造器的定義塊中,因為程序會將位於文檔注釋之後的第一個聲明與其相關聯。