Commenting

Comments increase cognitive load. Comments are a form of technical debt.

There can be both good and bad comments.

Comment on the "why" things work the way they are.

Good comments:

  • Legal/regulatory explanations on why it does what it does

Leave links to other resources:

  • Wikis

  • GitHub Issues or Pull Requests

  • Documentation

If comments are long and are not critical to be in the code, create a linkable resource, and use the link instead.

Dangers of bad comments:

  • Comments can be outdated and wrong

PreviousCreate Searchable NamesNextDon't commit commented code

Last updated