理解學習PHP編碼規範之注釋和檔案結構

來源:互聯網
上載者:User

檔案結構

|
|――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) {

  /* 以下代碼啟動並執行條件 */
  ...
}

尾端注釋

極短的注釋可以與它們所要描述的代碼位於同一行,但是應該有足夠的空白來分開代碼和注釋。若有多個短注釋出現於大段代碼中,它們應該具有相同的縮排。

以下是一個代碼中尾端注釋的例子:


if ($a == 2) {
  return TRUE; /* 對單一條件的說明 */
} else {
  return isPrime($a); /* 其餘的條件 */
}

行末注釋

注釋界定符"//",可以注釋掉整行或者一行中的一部分。它一般不用於連續多行的注釋文本;然而,它可以用來注釋掉連續多行的程式碼片段。以下是所有三種風格的例子:


if ($foo > 1) {

  // 第二種用法.
  ...
}
else {
  return false; // 說明傳回值的原因
}

//if ($bar > 1) {
//
//  // 第三種用法
//  ...
//}
//else {
  // return false;
//}

文檔注釋

文檔注釋描述php的類、構造器,方法,以及欄位(field)。每個文檔注釋都會被置於注釋定界符/**...*/之中,一個注釋對應一個類或成員。該注釋應位於聲明之前:


/**
 * 說明這個類的一些 ...
*/
class Example { ...


注意頂層(top-level)的類是不縮排的,而其成員是縮排的。描述類的文檔注釋的第一行(/**)不需縮排;隨後的文檔注釋每行都縮排1格(使星號縱向對齊)。成員,包括建構函式在內,其文檔注釋的第一行縮排4格,隨後每行都縮排5格。

若你想給出有關類、變數或方法的資訊,而這些資訊又不適合寫在文檔中,則可使用實現塊注釋(見5.1.1)或緊跟在聲明後面的單行注釋(見5.1.2)。例如,有關一個類實現的細節,應放入緊跟在類聲明後面的實現塊注釋中,而不是放在文檔注釋中。

文檔注釋不能放在一個方法或構造器的定義塊中,因為程式會將位於文檔注釋之後的第一個聲明與其相關聯。



相關文章

E-Commerce Solutions

Leverage the same tools powering the Alibaba Ecosystem

Learn more >

Apsara Conference 2019

The Rise of Data Intelligence, September 25th - 27th, Hangzhou, China

Learn more >

Alibaba Cloud Free Trial

Learn and experience the power of Alibaba Cloud with a free trial worth $300-1200 USD

Learn more >

聯繫我們

該頁面正文內容均來源於網絡整理,並不代表阿里雲官方的觀點,該頁面所提到的產品和服務也與阿里云無關,如果該頁面內容對您造成了困擾,歡迎寫郵件給我們,收到郵件我們將在5個工作日內處理。

如果您發現本社區中有涉嫌抄襲的內容,歡迎發送郵件至: info-contact@alibabacloud.com 進行舉報並提供相關證據,工作人員會在 5 個工作天內聯絡您,一經查實,本站將立刻刪除涉嫌侵權內容。