代碼才是最好的注釋

作者: 麒麟來源: 博客園發布時間: 2010-11-02 14:53 閱讀: 2964 次推薦: 3 原文鏈接 [收藏]

摘要：一直以來都存在代碼注釋的作用的討論。很多人認為注釋是不必要的，寫注釋那是因為代碼可讀性太差了。我也同意這個原則。如果必須添加注釋，我覺得可以添加一些解釋代碼為什么，而不是做什么的注釋。下面我舉個例子說明該如何除去代碼中的注釋。

　　一直以來都存在代碼注釋的作用的討論。很多人認為注釋是不必要的，寫注釋那是因為代碼可讀性太差了。我也同意這個原則。如果必須添加注釋，我覺得可以添加一些解釋代碼為什么，而不是做什么的注釋。下面我舉個例子說明該如何除去代碼中的注釋。

　　我們直接看代碼，下面的代碼是我要對注釋進行清除的例子。（這段代碼只是作為一個例子，沒有做過多的考慮。）

1 public String recommendGift(double budget){
2 // get gifts from helper
3 String[] gifts = giftHelper.getGifts();
4 String gift = null;
5
6 for (int i = 0; i < gifts.length; i++) {
7
8 gift = gifts[i];
9
10 // find out if gift already given
11 boolean isAlreadyGiven = false;
12 for (String given : giftsGiven) {
13 if(gift.equals(given)){
14 isAlreadyGiven = true;
15 break;
16 }
17 }
18
19 // calculate rating and budget
20 int x = rating * 200;
21 boolean ok = budget < x;
22
23 // if both conditions satisfy, give it.
24 if(!isAlreadyGiven && ok){
25 giftsGiven.add(gift);
26 // increment maintenance cost of the girlfriend
27 maintenanceCost += budget;
28 return gift;
29 }
30 }
31
32 return gift;
33 }

　　這段代碼是相當簡單的。從禮物清單中挑選出不在已贈送的禮物列表中的而且不超過預算的第一份禮物。這段代碼有如下幾個問題：

　　1、方法過長

　　2、這個方法做的事情太多

　　3、可讀性差，即使加了注釋

　　4、注釋告訴我們代碼是干什么的，這些應該是代碼自己的事情才對。

　　讓我們開始整理一下這段代碼。

　　首先，看下面代碼段，非常明顯，這些代碼注釋是不必要的。這種代碼注釋我們應該避免。它并沒有提高代碼的可讀性，事實上起到了相反的效果。

// get gifts from helper
String[] gifts = giftHelper.getGifts();

　　接著，我將下面帶注釋的代碼移動到一個分離的方法中。方法的命名可以來自給出的注釋。

// find out if gift already given
boolean isAlreadyGiven = false;
for (String given in giftsGiven) {
if(gift.equals(given)){
isAlreadyGiven = true;
break;
}
}

　　修改后的代碼：

private boolean isGiftNotAlreadyGiven(String gift) {
boolean isAlreadyGiven = true;
for (String given in giftsGiven) {
if(gift.equals(given)){
isAlreadyGiven = false;
break;
}
}
return isAlreadyGiven;
}

　　然后按照相同的方式繼續下去，最終的代碼如下：

public String recommendGift(double budget)
{
String recommendedGift = null;
for (String gift in giftHelper.getGifts())
{
recommendedGift = gift;
if(isGiftNotAlreadyGiven(recommendedGift)&&isUnderBudget(budget))
{
updateMaintenanceCostAndGiftsGiven(budget, recommendedGift);
return recommendedGift;
}
}
return recommendedGift;
}

private void updateMaintenanceCostAndGiftsGiven(double budget, String gift)
{
giftsGiven.add(gift);
maintenanceCost += budget;
}

private boolean isUnderBudget(double budget)
{
int x = rating * 200;
boolean ok = budget < x;
return ok;
}

private boolean isGiftNotAlreadyGiven(String gift)
{
boolean isAlreadyGiven = true;
for (String given in giftsGiven) {
if(gift.Equals(given)){
isAlreadyGiven = false;
break;
}
}
return isAlreadyGiven;
}

　　這里有幾件需要注意的事情：

　　1、一個大方法按照它的功能被分割成幾個小方法，這樣代碼就比較容易閱讀了。

　　2、每個方法大概4到5行，非常理想！

　　3、注釋去掉了，但是目的卻達到了。用代碼來代替了注釋。

　　譯自：Better way to comment.. code it.

　　譯者說明：

　　1、文章的那段代碼很有特色，正在戀愛的男程可以試一下代碼里面的方法。

　　2、確實用代碼來代替了注釋。

　　3、從文章可以看到這段代碼的演變主要是將注釋變成了函數名和變量名。

　　4、對于老外來說，英文和代碼類似，所以這樣做就非常受用，通過看函數名，變量名就能明白函數的功能，Clean Code書中也是這樣建議的。

　　5、對我們來說第一語言是中文的，英語不好情況就不一樣了，這就是為什么國人的建議大多要求注釋詳盡，讓代碼更易讀易懂；而老外的建議幾乎是盡可能的少。

　　6、我建議符合我們的國情：盡可能多的注釋。