Why Code Comments are a Code Smell: The Case for Self-Documenting Code

The Comment Conundrum: Why Less is Often More

In the world of software development, the debate over code comments has been a longstanding one. While some argue that comments are essential for clarity and maintainability, others see them as a necessary evil or even a “code smell.” In this article, we’ll delve into the argument that code comments, particularly those that explain what the code is doing, are indeed a code smell and why self-documenting code is the way to go.

The “What” vs. “Why” Dilemma

Comments that explain what the code is doing are often referred to as “what” comments. These comments are redundant and can quickly become outdated, leading to confusion and miscommunication. For instance, consider the following example:

# Adds one to x and returns the sum
def addOne(x):
    # Return the sum of x and 1
    return x + 1

Here, the comments are merely restating what the code is doing, which is already clear from the function name and the code itself. This kind of commenting adds noise and does not provide any real value.

On the other hand, “why” comments explain the reasoning behind the code. These comments are invaluable because they provide context that might not be immediately apparent from the code alone. For example:

# This optimization is necessary to avoid a performance bottleneck
# that occurs when dealing with large datasets.
def optimizeDataProcessing(data):
    # ...

In this case, the comment explains why the optimization is needed, which is crucial for understanding the intent behind the code.

The Problem with Redundant Comments

Redundant comments can lead to several issues:

1. Maintenance Overhead: Comments need to be maintained alongside the code. If the code changes and the comments are not updated, they can become misleading. This can lead to confusion and make the codebase harder to understand.

2. Code Smell: Comments that explain what the code is doing can be seen as a code smell because they indicate that the code itself is not clear. This suggests that the code needs refactoring to make it more self-explanatory.

3. Divergence: Over time, comments and code can diverge, making the comments less reliable. This divergence can lead to a situation where the comments are more harmful than helpful.

The Case for Self-Documenting Code

Self-documenting code is code that is clear and understandable without the need for additional comments. Here are some strategies to achieve this:

1. Descriptive Variable Names: Use variable names that clearly indicate their purpose. For example, instead of x, use userInputValue.

2. Clear Function Names: Function names should describe what the function does. For instance, calculateTotalCost is more descriptive than calc.

3. Modular Code: Break down complex logic into smaller, more manageable functions. This makes the code easier to understand and reduces the need for comments.

4. Tests: Write comprehensive tests to ensure the code behaves as expected. Tests can serve as a form of documentation, making it clear what the code is supposed to do.

Example: Refactoring for Clarity

Consider the following example of a function that generates a report:

# Creating Report
def run():
    vanilla_report = get_vanilla_report()
    tweaked_report = tweaking_report(vanilla_report)
    final_report = format_report(tweaked_report)
    # Sending Report
    send_report_to_headquarters_via_email(final_report)
    send_report_to_developers_via_chat(final_report)

# vs.

class ReportGenerator:
    def create_report(self):
        vanilla_report = self.get_vanilla_report()
        tweaked_report = self.tweaking_report(vanilla_report)
        return self.format_report(tweaked_report)

    def send_report(self, report):
        self.send_report_to_headquarters_via_email(report)
        self.send_report_to_developers_via_chat(report)

    def run(self):
        report = self.create_report()
        self.send_report(report)

In the refactored version, the code is more modular and self-explanatory. The need for comments is significantly reduced because the function names and structure clearly indicate what the code is doing.

Diagram: Refactoring for Clarity

Conclusion

While comments can be useful, they should be used judiciously. The goal should always be to write self-documenting code that is clear and understandable without the need for redundant comments. By following best practices such as using descriptive variable names, clear function names, and modular code, we can reduce the need for comments and make our codebases more maintainable.

So, the next time you’re tempted to add a comment to explain what your code is doing, take a step back and ask yourself: “Can I make this code clearer without comments?” The answer might just be yes, and that’s when you know you’re on the right track.