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