碰到神一般的境界：寫代碼的時候，只有上帝和他知道代碼是什麼意思，現在只有上帝知道了。
team work中經常的交流不是在討論問題，而是重構別人的代碼，之前有個任務真的是把我噁心到了，有大量複雜的邏輯代碼，木有註釋，看着大量的switch case，if else，再看看代碼量，上了800行的函數就有六個，我死的心都有了。
從我重構完代碼，我就發誓，造福後來者，寫代碼規範，有標準的註釋，函數不會在30秒內看不懂，有完整的測試用例，或者是demo。
先來給個簡單的註釋：
/**
* @author water(作者)
* @example /path/to/example(可以是實例demo或者是測試文檔也行，有了這個其他程序員使用的時候，運行一下就知道參數和返回值了)
* @param 參數，可能有好幾個
* @return 返回值
* @throws 方法拋出的異常
* @since 記錄什麼時候對文檔的哪些部分進行了更改(更改日誌)
*/要是想更少點，成員函數中的註釋就不需要這麼多了
/**
* @author water(作者)
* @example /path/to/example(可以是實例demo或者是測試文檔也行，有了這個其他程序員使用的時候，運行一下就知道參數和返回值了)
* @param 參數，可能有好幾個
* @return 返回值
*/額，好像還少了一個brief：函數簡介。總之就一句話，函數寫成一個黑盒子，看看註釋就能懂能用
例子請看這裏：PHP字符編碼
小技巧：
不能只是爲了這個註釋浪費很多時間？要效率？看這裏：
如果嫌每次寫這個註釋麻煩（我當時就是），可以把這個copy一份模板放到常用代碼中，使用的時候直接copy。
另外，更簡單的辦法就是更改zend studio或者eclipse中的模板，讓強大的IDE自動生成模板。
但是，裏面的比如參數，返回值，測試demo等，就必須由自己來改好了，木有這麼自動的
如果不會IDE自動生成模板的方法。哼！要度娘作甚！
下面是PHP的註釋標準：不爲別的，這個是PHPDOC的標準，寫好了註釋，也就寫好了API文檔：
PHPDocumentor是一個用PHP寫的工具，對於有規範註釋的php程序，它能夠快速生成具有相互參照,索引等功能的API文檔
| 標記 | 用途 | 描述 |
|---|---|---|
| @abstract | 抽象類的變量和方法 | |
| @access | public, private or protected | 文檔的訪問、使用權限. @access private 表明這個文檔是被保護的。 |
| @author | 張三 <[email protected]> | 文檔作者 |
| @copyright | 名稱 時間 | 文檔版權信息 |
| @deprecated | version | 文檔中被廢除的方法 |
| @deprec | 同 @deprecated | |
| @example | /path/to/example | 文檔的外部保存的示例文件的位置。 |
| @exception | 文檔中方法拋出的異常，也可參照 @throws. | |
| @global | 類型：$globalvarname | 文檔中的全局變量及有關的方法和函數 |
| @ignore | 忽略文檔中指定的關鍵字 | |
| @internal | 開發團隊內部信息 | |
| @link | URL | 類似於license 但還可以通過link找到文檔中的更多個詳細的信息 |
| @name | 變量別名 | 爲某個變量指定別名 |
| @magic | phpdoc.de compatibility | |
| @package | 封裝包的名稱 | 一組相關類、函數封裝的包名稱 |
| @param | 如 [$username] 用戶名 | 變量含義註釋 |
| @return | 如 返回bool | 函數返回結果描述，一般不用在void（空返回結果的）的函數中 |
| @see | 如 Class Login（） | 文件關聯的任何元素（全局變量，包括，頁面，類，函數，定義，方法，變量）。 |
| @since | version | 記錄什麼時候對文檔的哪些部分進行了更改 |
| @static | 記錄靜態類、方法 | |
| @staticvar | 在類、函數中使用的靜態變量 | |
| @subpackage | 子版本 | |
| @throws | 某一方法拋出的異常 | |
| @todo | 表示文件未完成或者要完善的地方 | |
| @var | type | 文檔中的變量及其類型 |
| @version | 文檔、類、函數的版本信息 |
