Fallacious Comment — Code Smells Catalog Skip to content

Fallacious Comment

Also known as: Comment, Attribute Signature and Comment are Opposite, Method Signature and Comment are Opposite

Lexical Abusers Names Code SmellLinguistic Antipattern Within Class

A comment that was true once but now lies. The code changed, the comment didn't, and there's no linter that catches the drift.

2 min read 3 sources

Overview

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 

1def rename_description(product, manufacturer):
2    """
3    Adds the manufacturer footer to the
4    products description.
5    """
6    ...
PYTHON

Refactoring

  • Remove Inconsistency

Sources

Browse All 56 Smells