iT邦幫忙

DAY 22
3

只是路過 HTML5 系列 第 22

程式基礎概念─註解說明

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

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

根據業界的統計,一個軟體的生命週期之中,有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


上一篇
程式基礎概念─變數命名規則
下一篇
JavaScript的語法架構
系列文
只是路過 HTML5 30

2 則留言

0
逮丸逮丸
iT邦大師 1 級 ‧ 2012-10-30 22:13:00

4 個空格做為自動縮排的數量

不同程式語言好像各有不同的縮排慣例:
Indent style
不曉得是不是要入境隨俗?
以前最常用tab,
而近來慣用兩個空格為縮排的單位,
若在html裡就不用左右拉來拉去,
或者terminal左右不夠而斷行。

看更多先前的回應...收起先前的回應...
iamya iT邦新手 2 級 ‧ 2012-10-30 22:40:35 檢舉

我本來也是用tab
後來查了資料筆記才知道tab大小會隨著各種編輯器不同><
不同程式語言好像有各自的寫法
我這邊寫的也沒有很詳細
小的筆記有時候寫的有點心虛,
如果有錯誤~再請大大指正謝謝

Albert iT邦高手 1 級 ‧ 2012-10-30 22:51:34 檢舉

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

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

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

過度描述 是 翻譯 不是 描述, 又不是 [土產團隊]
用華文, 愛爾蘭, 德國團隊成員 看不懂

albertachen 說:用華文, 愛爾蘭, 德國團隊成員 看不懂

"規則引擎"不能幫他們轉換成他們看的懂啊~~~~

Albert iT邦高手 1 級 ‧ 2012-11-03 18:35:47 檢舉

還要翻 還要譯 哪就太好了

感謝你

請參考全球
金控基金
高等教育
政府機構最多人使用的 peoplesoft rule engine

我要留言

立即登入留言