Navs
Code Smells Catalog
Fallacious Comment

Last Revision — April 19, 2022

2 Min Read


  • Also Known As

    Comment Attribute Signature and Comment are Opposite Method Signature and Comment are Opposite

  • Obstruction

    Lexical Abusers

  • Occurrence

    Names

  • Expanse

    Within a Class

  • Related Smells

    - "What" Comment (family)
    - Fallacious Method Name (family)
    - Duplicated Code (caused)

  • History

    Marcel Jerzyk in thesis (2022): "Code Smells: A Comprehensive Online Catalog and Taxonomy"

    Venera Arnaoudova in paper (2015): "Linguistic Antipatterns: What they are and how developers perceive them"

    Martin Fowler in book (1999): "Refactoring: Improving the Design of Existing Code"

Fallacious Comment

Comments differ from most other syntaxes available in programming languages; it is not executed. This might lead to situations where, after code rework, the comments around it were left intact and no longer true to what they described. First and foremost, this situation should not even happen, as good comments from the "Why" Comment family are not susceptible to this situation. If the comment explained "what" was happening, then it will be relevant as long as the code it explains is intact. Of course, "What" Comments are a Code Smell themselves, and so is Duplicated Code.

This might generally happen within docstrings in real-life scenarios, which developers usually find in methods exposed to other users.

Causation

The developer was in a hurry and did not double-check that everything was up-to-date after the changes. A passing unit test could also reaffirm him - there is no practical automated way to check for the correctness of comments/docstrings.

Problems

Decreased Readability

The developer does not know whether he should trust the method's signature or comment.

Example

"What" Comment and Fallacious Comment.

Smelly

def rename_description(product, manufacturer):
    """
    Adds the manufacturer footer to the
    products description.
    """
    ...

Solution

def add_manufacturer_footer_to_product_description(product, manufacturer):
    ...

Refactoring:

  • Remove Inconsistency

Sources
  • [Origin] - Marcel Jerzyk, "Code Smells: A Comprehensive Online Catalog and Taxonomy" (2022)
  • [Parentage1] - Venera Arnaoudova, Massimiliano Di Penta, Giuliano Antoniol "Linguistic Antipatterns: What they are and how developers perceive them" (2015)
  • [Parentage2] - Martin Fowler, "Refactoring: Improving the Design of Existing Code" (1999)