代码才是最好的注释



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

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

  
  

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

　　这里有几件需要注意的事情：

　　1、一个大方法按照它的功能被分割成几个小方法，这样代码就比较容易阅读了。

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

　　3、注释去掉了，但是目的却达到了。用代码来代替了注释。

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

　　译者说明：

　　1、文章的那段代码很有特色，正在恋爱的男程可以试一下代码里面的方法。

　　2、确实用代码来代替了注释。

　　3、从文章可以看到这段代码的演变主要是将注释变成了函数名和变量名。

　　4、对于老外来说，英文和代码类似，所以这样做就非常受用，通过看函数名，变量名就能明白函数的功能，Clean Code书中也是这样建议的。

　　5、对我们来说第一语言是中文的，英语不好情况就不一样了，这就是为什么国人的建议大多要求注释详尽，让代码更易读易懂；而老外的建议几乎是尽可能的少。