Last Revision — April 19, 2022
2 Min Read
Comment Attribute Signature and Comment are Opposite Method Signature and Comment are Opposite
Lexical Abusers
Names
Within a Class
- "What" Comment (family)
- Fallacious Method Name (family)
- Duplicated Code (caused)
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"
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.
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.
The developer does not know whether he should trust the method's signature or comment.
"What" Comment and Fallacious Comment.
def rename_description(product, manufacturer):
"""
Adds the manufacturer footer to the
products description.
"""
...
def add_manufacturer_footer_to_product_description(product, manufacturer):
...