Terry的Blog

三、注釋與文檔

首先討論一個計算工作量的數學模型。

1.沒有注釋的情況下：
第一次開發工作量＝代碼行數×單位代碼工作量
維護工作量＝理解代碼工作量＋決定方案工作量＋修改代碼行數×單位代碼工作量

2、有注釋的情況下：
第一次開發工作量＝代碼行數×單位代碼工作量＋代碼行數×注釋率×單位注釋工作量
維護工作量＝基于注釋理解代碼工作量＋決定方案工作量＋修改代碼行數×單位代碼工作量＋修改代碼行數×注釋率×單位注釋工作量

增加注釋之后，增機了注釋的工作量，這些增加需要通過節約理解代碼的工作量賺回來。

3、理解代碼的工作量討論
在沒有注釋的情況下：
理解代碼工作量＝代碼總量×理解代碼的效率
在有注釋的情況下：
理解代碼工作量＝注釋總量×理解注釋的效率
又因為
注釋總量＝代碼總量×注釋率

因此，要想通過注釋減少維護工作量，就要切實降低注釋率，并且提高注釋的效率。

4、這些數據的含義

注釋率：軟件的注釋行數/軟件的程序行數

有人像這樣寫代碼

java代碼:

//給i賦初始值 
int i=10; 
//開始循環 
for(int j=0;j<i;j++){ 
//輸出j的值 
System.out.println(j); 
}//循環結束 

這樣的一比一注釋，注釋率就是1。一般來說，注釋率大于1的程序，肯定是垃圾。因為寫這個程序的人，根本不知道該注釋哪些地方。

但是，并不是說注釋率越低越好，因為注釋少了之后，可能會影響理解注釋的效率。

面對一次維護需求時：
理解注釋的效率：需要閱讀的注釋行數/注釋總數

如果一個維護者，在閱讀了所有的注釋之后，還沒有理解程序，更不要說找到解決方案，那么他就必須去閱讀代碼。理解代碼的工作量，就是沒有注釋時的工作量再加上被垃圾注釋浪費掉的工作量。

這時的理解注釋的效率，就是大于1的。寫出這樣的注釋的人，不配做程序員。

切實提高理解注釋的效率，是提高維護效率的根本。可以有以下手段：
1、結構化文檔
2、HTML格式的合理的超鏈接
3、關鍵字索引（方便對于注釋全文檢索）
4、邏輯清晰的概要介紹

上面的這些公式都有一條：決定方案工作量。
這個工作量其實是可以合并的。以往的理解是，必須理解了現有的程序，才能決定維護的方案。但是我們可以假設，如果通過查詢注釋和文檔，就能找到如何維護的答案，那么這樣的維護就是最輕松的。

我們不假設所有的維護都能通過查詢注釋和文檔，直接得到答案，但是如果有一個預先的合理的考慮，而寫下了系統維護指南這樣的文檔，那么這樣的文檔，將是最有價值的。

另外一個手段，就是在每次維護之后，寫下一個維護記錄，大致格式是：
我的維護需求，我查詢了哪些注釋和文檔，最后我在哪里找到了答案

這樣的記錄，將會為后來者提供極大的方便。

下面說一點題外話，因為在軟件工程中，還存在這樣的文檔：
《功能需求描述》《概要設計》《詳細設計》《.......》
我不理解為什么需要這樣的文檔，也不理解誰會來閱讀這樣的文檔。為了模仿建筑工程，軟件工程已經大大的扭曲了自己的本性。

注釋與文檔的本質，是為了便于軟件的開發和維護，而不是在一道一道的工序之間作為“交接班”的說明。

如果一份文檔，無法回答這兩個問題，那么這份文檔就是浪費了：

誰愿意寫這樣的文檔？

更多評論

下面說一點題外話，因為在軟件工程中，還存在這樣的文檔：
《功能需求描述》《概要設計》《詳細設計》《.......》
我不理解為什么需要這樣的文檔，也不理解誰會來閱讀這樣的文檔。為了模仿建筑工程，軟件工程已經大大的扭曲了自己的本性。

——顯然你肯定還沒有參與大型的團隊項目，所以有這樣的疑問也不奇怪。
文檔不僅僅是交接，而是思想的直接表達與傳承方式。

Terry的Blog

軟件開發的評價標準（轉載）

評論

# re: 軟件開發的評價標準（轉載）回復 更多評論

常用鏈接

留言簿(2)

隨筆分類(81)

隨筆檔案(56)

Blog

web sites

其他

軟件下載

積分與排名

最新評論

閱讀排行榜

Terry的Blog

軟件開發的評價標準（轉載）

評論

# re: 軟件開發的評價標準（轉載） 回復 更多評論

常用鏈接

留言簿(2)

隨筆分類(81)

隨筆檔案(56)

Blog

web sites

其他

軟件下載

積分與排名

最新評論

閱讀排行榜

# re: 軟件開發的評價標準（轉載）回復更多評論