程式碼才是最好的註釋

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

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

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;
  }

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

    private boolean isUnderBudget(double budget)
    {
        int x = rating *200;
        boolean ok = budget         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、我建議符合我們的國情：儘可能多的註釋。