php註釋標準

4.1 塊註釋

塊註釋通常用於提供對文件，方法，數據結構和算法的描述。塊註釋被置於每個文件的開始處以及每個方法之前。它們也可以被用於其他地方，比如方法內部。在功能和方法內部的塊註釋應該和它們所描述的代碼具有一樣的縮進格式。

塊註釋之首應該有一個空行，用於把塊註釋和代碼分割開來，比如：


/*
* 這裏是塊註釋
*/


塊註釋可以以/*-開頭，這樣indent(1)就可以將之識別爲一個代碼塊的開始，而不會重排它。


/*-
* 如果想被忽略，可是使用特別格式的塊註釋
*
* one
* 　　two
* 　　　　three
*/


注意：如果你不使用indent(1)，就不必在代碼中使用/*-，或爲他人可能對你的代碼運行indent(1)作讓步。
4.2 單行註釋

短註釋可以顯示在一行內，並與其後的代碼具有一樣的縮進層級。如果一個註釋不能在一行內寫完，就該採用塊註釋。單行註釋之前應該有一個空行。以下是一個代碼中單行註釋的例子：


if (condition) {

/* 以下代碼運行的條件 */
...
}

4.3 尾端註釋

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

以下是一個代碼中尾端註釋的例子：


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

4.4 行末註釋

註釋界定符"//"，可以註釋掉整行或者一行中的一部分。它一般不用於連續多行的註釋文本；然而，它可以用來註釋掉連續多行的代碼段。以下是所有三種風格的例子：


if ($foo > 1) {

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

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

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


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


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

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

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