↓ Ir para o conteúdo principal

← todas as notas

📎 Webclip

Comment Only What the Code Cannot Say

Henney says comments are useful only when they add something code cannot say. Comments that repeat code, preserve commented-out code, or replace a better name or structure create noise and distraction, so they should be removed or rewritten.

Reading notes
#

  • Good comments require judgment about what not to write, just like good writing in general.
  • Comments that are wrong are harmful, and incorrect comments can survive in a codebase longer than code errors.
  • Comments that restate code add no value, because they repeat knowledge already expressed in code.
  • Commented-out code has no useful effect and becomes stale quickly; version control handles history better.
  • Noisy and wrong comments can make programmers ignore comments altogether.
  • Comments should be treated like code and kept only when they add value for the reader.
  • If a comment explains something the code should already make clear, the code should change instead.
  • Better variable, method, class, and test names can remove the need for explanatory comments.
  • Long functions should often be split into smaller functions so the code structure carries the intent.
  • The useful comment is the one that fills the gap between what code can express and what the reader still needs to know.