代码才是最好的注释

by 麒麟

at 2010-10-30 01:54:00

original http://www.cnblogs.com/zhuqil/archive/2010/10/30/1864882.html

一直以来都存在代码注释的作用的讨论。很多人认为注释是不必要的，写注释那是因为代码可读性太差了。我也同意这个原则。如果必须添加注释，我觉得可以添加一些解释代码为什么，而不是做什么的注释。下面我举个例子说明该如何除去代码中的注释。

我们直接看代码，下面的代码是我要对注释进行清除的例子。（这段代码只是作为一个例子，没有做过多的考虑。）

 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 &lt; 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 &lt; x; 
22      
23      // if both conditions satisfy, give it. 
24      if(!isAlreadyGiven &amp;&amp; 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;
    }