php注釋標準

4.1 塊注釋

塊注釋通常用於提供對檔案，方法，資料結構和演算法的描述。塊注釋被置於每個檔案的開始處以及每個方法之前。它們也可以被用於其他地方，比如方法內部。在功能和方法內部的塊注釋應該和它們所描述的**具有一樣的縮排格式。

塊注釋之首應該有乙個空行，用於把塊注釋和**分割開來，比如：

/** 這裡是塊注釋

*/塊注釋可以以/*-開頭，這樣indent(1)就可以將之識別為乙個**塊的開始，而不會重排它。

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

** one

* 　　two

* 　　　　three

*/注意：如果你不使用indent(1)，就不必在**中使用/*-，或為他人可能對你的**執行indent(1)作讓步。

4.2 單行注釋

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

if (condition)

4.3 尾端注釋

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

以下是乙個**中尾端注釋的例子：

if ($a == 2) else

4.4 行末注釋

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

if ($foo > 1)

else

//if ($bar > 1)

//else

4.5 文件注釋

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

/*** 說明這個類的一些 ...

*/class example { ...

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

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

文件注釋不能放在乙個方法或構造器的定義塊中，因為程式會將位於文件注釋之後的第乙個宣告與其相關聯。