Deodorant Comment: Communication Breakdown
Deodorant Comment
“Comments often are used as a deodorant.”
— Martin Fowler and Kent Beck, Refactoring, page 87
This smell occurs when you use comments to explain code, rather than making your code self-documenting or intention-revealing.If you write intention-revealing code, your code is so easy to understand that comments become unnecessary.
If, on the other hand, your code isn't easy to understand, comments can help explain the code.As you'll see in the upcoming quiz, there are cases where using comments is acceptable or unacceptable.In his book, Refactoring, Fowler says that when you write a comment to make it easier to understand some code,
you are trying to reduce the "odor" of the code. In general, it is far better to refactor the code to make it
understandable rather than simply writing a comment for it.Programmers who write automated tests have also come to learn that well-written tests help document what code does.
So even if you make your code intention-revealing, automated test code can help reveal the expected behavior of the code.
— Martin Fowler and Kent Beck, Refactoring, page 87
(Reading...)
Formatting Hints:
To format... | use this markup: |
---|---|
source code | {source:lang=java|lineNumbers=false}...{source} (Supported languages: java, cpp, csharp, c, python.) |
bold text | __some text__ |
italicized text | ~~some text~~ |
underlined text | @@some text@@ |
a method or class name | ``myMethod(...)`` |