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
Last modified 2yr ago