Comments

Version 1.2 by chrisby on 2023/11/18 23:45

General Guidelines

  • Code should speak for itself. It is better to explain things in and through the code. Comments are at best a necessary evil when you can't express something in code.
  • Comments can lie because they are hard to maintain. When the code changes, the comments are usually forgotten or ignored.
  • Comments are no substitute for bad code.

Good Comments

  • Legal comments: Copyrights, Authors. It's best to reference a standard license or external document so as not to deface the code.
  • Informative comments
  • Statement of intent
  • Clarifications
  • Warnings of consequences
  • TODO comments
  • Reinforcement of code that is otherwise perceived as unimportant
  • Javadocs in public API's.

Bad Comments

  • Whispers
  • Redundant comments
  • Misleading comments
  • Prescriptive comments
  • Diary comments
  • Chatter
  • Position identifier
  • Comments after closing parentheses to emphasize sections that may be useful for long functions. They should be avoided and the function shortened.
  • Attributions
  • Asides
  • Commented code
  • HTML comments
  • Non-local information
  • Too much information
  • Unclear context
  • Function header
  • Javadocs in non-public API's