Notes from the book Clean Code

• When comments are good –
  • legal comments
  • providing information eg – information about an abstract method.
  • explaining intent
  • clarifying some obscure argument or return value.
  • add warnings
  • for TODOs
  • java docs
• When comments are bad –
  • any comment that makes you look at other parts of code to understand it’s meaning.
  • redundant comments, not required as the code itself is explanatory, might even confuse/mislead the reader. Unnecessary comments even obscure and reduce readability, eg, too many Javadoc comments.
  • journal comments
  • Javadoc comments before every method and variable are too much. Javadocs in nonpublic methods
  • Misleading comments
  • Position markers
  • the comment that could have been code.
  • Function headers
  • comments with too much information