Stack Overflow has a great blog post on commenting best practices: https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/
@Adam Haney‘s golden rule for comments:
Comments should explain why code does something, not what it does. For example if code does something special because of a business requirement, as a workaround to a bug in a library or because of a bug in the past explain the context.
We strive to make everyone feel welcome at Invisible. There is some terminology that is common in the engineering community that might unintentionally make some of our team members feel excluded. There are easy replacements that we can make to make sure everyone feels included. For additional information about terminology visit inclusivenaming.org
Term | Use Instead | Link |
---|---|---|
Whitelist, Blacklist | allowlist/denylist OR allowed<Nouns>/denied<Nouns> | https://inclusivenaming.org/word-lists/tier-1/#whitelist-blacklist |
Master, slave | Leader/follower, Parent/child | https://inclusivenaming.org/word-lists/tier-1/#master-slave |
Master | main, original, source, control plane | https://inclusivenaming.org/word-lists/tier-1/#master |
Sanity check / Sanity test | confidence check, coherence check, test, verification | https://inclusivenaming.org/word-lists/tier-2/#sanity-checksanity-test |