linkRule 1: Comments should not duplicate the code.

You probably won't need to place a lot of comments if you think carefully about how you name your functions and variables.

But with some complex functions, it can make your code more readable and easier to understand.

linkRule 2: Good comments do not excuse unclear code.

If you need to explain something, think about if you can make it clear by editing the code.

Think of variable names, function names

linkRule 3: If you can’t write a clear comment, there may be a problem with the code.

If it's complex and you can't really explain what's going on it could be worth it re-examine the code.

linkRule 4: Comments should dispel confusion, not cause it.

Keep it short and concise.

linkRule 5: Explain unidiomatic code in comments.

If it's not exactly clear why the code is there, you can explain your design choice right above the function someone else might see as redundant.

linkRule 6: Provide links to the original source of copied code.

Including a reference to the source enables future readers to get the full context, such as:

linkRule 7: Include links to external references where they will be most helpful.

Links to standards and other documentation can help readers understand the problem your code is solving. While this information may be somewhere in a design document, a well-placed comment gives readers the pointer when and where it is most needed.

linkRule 8: Add comments when fixing bugs.

Comments should be added not just when initially writing code but also when modifying it, especially fixing bugs.

It can also be helpful to reference issue trackers:

linkRule 9: Use comments to mark incomplete implementations.

Use TODO comments for any ideas for improvements, this will raise your overal Code Quality in the long run.

link📡 Resources