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

Create Searchable Names

Don't commit commented code

Last modified 2yr ago

Copy link