註解如果寫得不好，即使是寫中文、也容易看得霧煞煞> <

今天來分享，關於程式註解的相關筆記。

根據業界的統計，一個軟體的生命週期之中，有80%是花在維護上面，
讓他人容易讀懂和維護你的code，對於軟體的成功和演進至關重要。

如何寫出優良的程式?
注意整體接口，而不是局部實現。

那要不要註解?

清楚的程式架構，可以減少或無須註解，
高手可以讓程式本身就寫得很簡潔清楚，不依賴註解。

總是希望自己程式可以寫得漂亮乾淨一點。

但因為我現在菜鳥程度、腦袋也不好，
還沒有辦法快速讓自己程式邏輯寫的很簡潔。
只好先學習命名規則和風格、以及註解，去做一些努力摟！

註解如果寫得不好，即使是寫中文、也容易看得霧煞煞> <

今天來分享，關於程式註解的相關筆記。

*只寫有意義的註解
避免多餘的註解，註解應該是說明Why，而不是How和What
程序註解應該是告訴別人你的目的，而不是告訴別人程式的語法。

例如:

if(i<0) //如果i小於0
{
i=0; //i等於0
}

*直接就看得出意思的變數命名或函數命名
例如:

GetComputerName()，isAdmin

可以減少註解，直接從變數名稱上得知其涵意。

*4 個空格做為自動縮排的數量
各種編輯器和IDE的tab大小不一，使用空格最能統一標準。

*在編寫程式碼時添加註解，此時它們在你腦中還是清晰的。

備註:讓控制結構的前括號獨立成行
(太過緊密的code容易讓除錯時失焦，節省大括號的結果可能會造成邏輯錯誤。

http://www.csie.nctu.edu.tw/~skyang/naming.zhtw.htm
另外上方這個網站，有特別列出註解範本，
寫得蠻好的，部分內容如下，很值得參考。

檔案註解範本: 說明這份程式碼檔案內所包含的內容、以及實現的功能。

/** @file 檔案名稱
  * @brief 檔案簡短描述.

  * 檔案詳細描述, 內容包含哪些函式或類別, 實作了哪些功能, 

  * @author 作者名稱 (電子郵件或員工編號)
  * @date 更新日期 */

結構體/類別註解範本(包括資料成員):
在每個 struct 或 class 宣告之前，先以一段註解敘述此結構體或類別的內容與角色，
然後再以 ///< 註解逐項說明各資料成員的意義。

/** @brief 類別或結構體簡述.

  * 類別或結構體詳細描述，包括欄位內容、原理、相依性(dependency)... */
struct CLASSNAME
{
    datatype member;    ///< 資料成員的描述


};

函式註解範本(包括函式成員): 在撰寫函式的程式碼(或原型宣告)之前，
先以一段註解敘述此函式所要達成的功能，以及達成此功能的原理，
再以 @param 逐項地解釋函式中每個輸入參數的意義與限制。

/** @brief 函式簡短描述.

  * 函式的詳細描述，包括原理，需求，適用範圍...

  * @param param_out 輸出參數的描述
  * @param param_in  輸入參數的描述
  * @return 傳回值的意義. */

其他參考:
(翻譯) 註解程式碼的13個建議 (C/C++)
http://www.cnblogs.com/oomusou/archive/2008/04/26/1172208.html
編程命名中的7+1個提示
http://coolshell.cn/articles/1038.html
編程中的命名設計那點事
http://coolshell.cn/articles/990.html