The StackOverflow blog describes [best practices for writing code comments](https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/). Rule 1: Comments should not duplicate the code. Rule 2: Good comments do not excuse unclear code. - The need for comments can often be eliminated with better variable naming Rule 3: If you can't write a clear comment, there may be a problem with the code. - See [[Kernighan's Law]] Rule 4: Comments should dispel confusion, not cause it. Rule 5: Explain unidiomatic code in comments. - Comment when the code might be simplified by someone who doesn't understand why it is so verbose (often because an upstream package has some unusual behavior you need to guard against.) Rule 6: Provide links to the original source of copied code. Rule 7: Include links to external references where they will be most helpful. Rule 8: Add comments when fixing bugs. - Especially when the bug requires a workaround in the code. Rule 9: Use comments to mark incomplete implementations. - `TODO` is a common marker for incompleteness, and some IDEs have methods to find these quickly