Smell Detail

Comments

注释

Dispensables

Too many comments in the code usually indicate that the code is not clear enough.

Define

Introduction

Although comments are useful, too many comments usually indicate that the code itself is not clear. Good code should be self-explanatory, and comments should explain "why" instead of "what".

Key Identifiers

  • Comments explain obvious code
  • Comments are out of sync with the code
  • A large number of inline comments
  • More comments than code

Refactoring Suggestions

  1. Extract Method: Replace comments with meaningful method names
  2. Introduce Explaining Variable: Use variable names to explain complex expressions
  3. Rename: Use clearer variable and method names
  4. Remove Redundant Comments: Keep only truly valuable comments

Explanation

These comments are redundant because the code is already clear. They should be removed to make the code more concise, or replaced with better naming to make the code self-explanatory.

Code Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
class Calculator {
    // This method calculates the sum of two numbers
    public int add(int a, int b) {
        // Add the first number and the second number
        int result = a + b;
        // Return the result
        return result;
    }
    
    // This method calculates the area of a circle
    // Parameter r is the radius
    // Return value is the area
    public double calculateCircleArea(double r) {
        // Use the formula π * r * r
        double pi = 3.14159; // Value of π
        double area = pi * r * r; // Calculate area
        return area; // Return the calculation result
    }
    
    // This method checks if a number is even
    public boolean isEven(int number) {
        // If the remainder of number divided by 2 is 0, then it's even
        if (number % 2 == 0) {
            return true; // Return true
        } else {
            return false; // Return false
        }
    }
    
    // Calculate factorial
    // Input: a positive integer n
    // Output: factorial of n
    public int factorial(int n) {
        // If n equals 0 or 1, return 1
        if (n <= 1) {
            return 1;
        }
        // Otherwise return n multiplied by factorial of (n-1)
        return n * factorial(n - 1);
    }
}