Code is the best comment

There has always been a discussion about the role of code annotations. Many people think that comments are unnecessary. Writing comments is because the code is too readable. I also agree with this principle. If you must add comments, I think you can add comments that explain why the code is not. The following example shows how to remove the comments in the code.

Let's look at the Code directly. The following code is an example of clearing comments. (This code is just an example without too much consideration .)

  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      }

This code is quite simple. Select the first gift from the gift list that is not in the gift list and does not exceed the budget. This Code contains the following issues:

1. The method is too long.

2. This method does too many things.

3. Poor readability, even with comments

4. Comments tell us what the code is doing. These should be the code's own things.

Let's get started with this code.

First, look at the following code snippet. Obviously, these code annotations are unnecessary. We should avoid such code comments. It does not improve the readability of the Code, in fact it has the opposite effect.

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

Next, I will move the following code with annotations to a separate method. The method name can come from the comments.

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

Modified code:

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

Then proceed in the same way. The final code is as follows:

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

There are several things to note:

1. A large method is divided into several small methods according to its functions, so that the code is easier to read.

2. Each method contains 4 to 5 rows, Which is ideal!

3. The comment is removed, but the goal is achieved. Use code to replace comments.

Translated from: Better Way to comment... code it.

Translator's note:

1. The code in the article is very distinctive. If you are in love, you can try the method in the code.

2. The comments are indeed replaced by code.

3. From the article, we can see that the evolution of this Code mainly changes annotations into function names and variable names.

4. for foreigners, the English language is similar to the code, so this is very useful. by looking at the function name, the variable name can understand the function of the function. This is also recommended in the clean code book.

5. For us, the first language is Chinese, and the poor English is different. This is why most Chinese suggestions require detailed comments to make the code easier to read and understand; there are almost as few suggestions as possible for foreigners.

6. I suggest meeting our national conditions: Add as many comments as possible.