在代碼中添加合適的注釋來(lái)注解代碼可以代碼的可讀性，可以使得自己和團(tuán)隊(duì)其他成員在之后的代碼的審查和維護(hù)中更加省時(shí)省力。

一、注釋格式說(shuō)明

1.類或文件注釋

• 類或文件注釋使用 PEAR 推薦的多行注釋方式，不能使用 // 來(lái)注釋：

• 所有類必須添加說(shuō)明信息，推薦項(xiàng)目包括：創(chuàng)建者信息、創(chuàng)建時(shí)間、更新時(shí)間、更新說(shuō)明、版本號(hào)、程序（文件）描述、項(xiàng)目名稱等，注釋信息可根據(jù)需要添加或減少。

例：

/**
* @access        該標(biāo)記用于指明關(guān)鍵字的存取權(quán)限：private、public或proteced使用范圍：class,function,var,define,module
* @author        指明作者
* @copyright     指明版權(quán)信息
* @const         使用范圍：define 用來(lái)指明php中define的常量
* @final         使用范圍：class,function,var 指明關(guān)鍵字是一個(gè)最終的類、方法、屬性，禁止派生、修改。
* @global        指明在此函數(shù)中引用的全局變量
* @name          為關(guān)鍵字指定一個(gè)別名。
* @package       用于邏輯上將一個(gè)或幾個(gè)關(guān)鍵字分到一組。
* @abstrcut      說(shuō)明當(dāng)前類是一個(gè)抽象類
* @param         指明一個(gè)函數(shù)的參數(shù)
* @return        指明一個(gè)方法或函數(shù)的返回值
* @static        指明關(guān)建字是靜態(tài)的。
* @var           指明變量類型
* @version       指明版本信息
* @todo          指明應(yīng)該改進(jìn)或沒(méi)有實(shí)現(xiàn)的地方
* @link          可以通過(guò)link指到文檔中的任何一個(gè)關(guān)鍵字
* @ingore        用于在文檔中忽略指定的關(guān)鍵字
*/

2.方法函數(shù)注釋

• 方法函數(shù)外部說(shuō)明使用 PEAR 推薦的多行注釋方式，不能使用 // 來(lái)注釋
• 方法函數(shù)內(nèi)部代碼注釋時(shí)單行使用 // 注釋，多行使用 /** ... */ 來(lái)注釋

3. 抽象方法注釋

• 抽象方法說(shuō)明使用 PEAR 推薦的多行注釋方式，不能使用 // 來(lái)注釋
• 必須說(shuō)明返回值、參數(shù)和實(shí)現(xiàn)功能

4.代碼注釋

• 使用 // 來(lái)單行注釋代碼片段、業(yè)務(wù)邏輯等
• 使用 /** ... */ 來(lái)多行注釋代碼片段、業(yè)務(wù)邏輯等

5.特殊注釋

• // TODO ：標(biāo)記待辦的業(yè)務(wù)邏輯

反例：

//我要做的事
if (true) {
    // TODO
}

• // FIXME ：存在錯(cuò)誤，需要修補(bǔ)

反例：

//我要做的事
if (true) {
    //do something
    // FIXME
}

二、其他說(shuō)明

• 注釋內(nèi)容必須在注釋對(duì)象之前，不能再同一行

反例：

//我要做的事
if (true) {
    //TODO
}

• 注釋中建議使用中文，不建議使用英文
• 注釋要與注釋對(duì)象對(duì)齊
• 后期修改代碼時(shí)要同時(shí)修改注釋
• 注釋掉的代碼要盡量使用注釋說(shuō)明
• 注釋最好不要太多，必要之處加以注釋即可，語(yǔ)義清晰之處盡量不要使用注釋，以免本末倒置，增加后期代碼維護(hù)的工作量

由于本人學(xué)藝不精，未盡之處還望海涵，有誤之處請(qǐng)多多指正，歡迎大家批評(píng)指教

本文 完