↓ Ir para o conteúdo principal

← todas as notas

📎 Webclip

Why Comments Are Stupid, a Real Example

The author argues that comments often appear because code is not naming things clearly enough or because methods are too large. After reading Code Complete and Clean Code, he came to see comments as a sign that code should express intent better on its own.

He uses a .NET Framework method, SplitDirectoryFile, to show how comments can be replaced by clearer variable names, smaller methods, and a class that encapsulates the logic. The refactor removes comments while keeping the code understandable, and the author says code that communicates intent directly is easier to maintain.

Reading notes
#

  • Comments often cover for weak naming or methods that are too large.
  • Better naming can communicate assumptions that were previously written as comments.
  • A method can sometimes be replaced by a clearer helper or a boolean or value that makes the intent explicit.
  • Refactoring the example into a class helps express the logic more clearly.
  • The author treats the refactor as a net gain because code changes, while comments often do not.