"What" Comment — Code Smells Catalog Skip to content

"What" Comment

Also known as: Comment

Dispensables Names Code Smell Within Class

Comments that narrate what the code does instead of why — a deodorant sprayed over smelly code, where extracting a well-named method would eliminate both the smell and the comment.

3 min read 3 sources

Overview

Recognizing all comments as Code Smells is controversial and raises many different opinions. For this reason, I define a concrete subcategory of comments named “What” Comments that clearly defines only these comments, which in the vast majority will hint at something smells. The rule is simple: If a comment describes what is happening in a particular code section, it is probably trying to mask some other Code Smell.

This distinction leaves room for the “Why” Comments which were already defined by Wake in 2004 and were considered helpful. Wake also notes that comments that cite non-obvious algorithms are also acceptable [1]. I wanted to mention that comments may have their places in a few more cases, such as extreme optimizations, note discussion conclusions for future reference after a code review, or some additional explanations in domain-specific knowledge.

The problem is that Comments are generally smelly, as I have mentioned. This is because they are a deodorant for other smells [2]. They may also quickly degrade with time and become another category of comments Fallacious Comments, which are a rotten, misleading subcategory of [“What” Comments].

Causation

The author sees that the code is confusing and tries to be helpful by adding explanations.

Problems

📋
Duplication

Bad docstrings, which are just duplicating everything that can be understood from the method name and parameter names & type annotations, are cluttering the code, possibly sooner or later on the first occasion, they might become Fallacious Comments.

⚠
Cover up for other smells

A comment that must explain what is happening in the code indicates that it can't speak for itself, which is a strong indicator of present code smells.

Example 

1class Foo:
2    def run(...):
3        ...
4
5        # Creating Report
6        vanilla_report = get_vanilla_report(...)
7        tweaked_report = tweaking_report(vanilla_report)
8        final_report = format_report(tweaked_report)
9
10        # Sending Report
11        send_report_to_headquarters_via_email(final_report)
12        send_report_to_developers_via_chat(final_report)
13        ...
PYTHON
1def get_gross_value(p, t):
2    """
3    params
4     - price: float
5     - tax: float
6    """
7    ...
PYTHON
Example of useless comment as a docstring.
1def increase_attack(self, value: int):
2    """ Increases attack by the given value.
3
4    params:
5      - value: integer
6    """
7    self.attack += value
PYTHON

Refactoring

  • Extract Method
  • Rename Method
  • Introduce Assertion

Sources

Browse All 56 Smells