0atman's Second Rule

January 21, 2016

Line comments are apologies to your future self.

It’s partly pragmatism:

Whenever you feel the need to comment a block of code, which could even be as little as a single line and make the total code longer then the code it replaces, you should encapsulate it into another function given that the function name clearly explains the purpose of the code.

What should be decisive in the decision to encapsulate functionality is not code length but semantic distance between what the function does and how it does it.

Refactoring, Martin Fowler, p. 76-77

But it’s also that, given the above, comments are very likely to be code smells, indicating bad code that NEEDED a comment.