Comments
Comments should always add value to the person reading the code.
Comments that do not add value should be removed
otherwise it distracts the reader
Should not explain what the code is doing, if it is hard to follow then need to refactor
Should not explain the language
The reader should know the language
Should explain why this decision was taken
To come back to the code and make changes, ie todos
If the code is going to be provided as a library to people to use as an API, or there is a need to auto-generate documentation, then XML comments may still need to be provided.
Do not comment every line
Comments are evil. The goal of comments is to compensate for our failure or to help express ourselves better.
They are always sign of failure.
Comments get outdated as there is no good way of maintaining them.
People move the code but forget the comment.
People change the code but forget the comment, or no longer remember what it was supposed to mean.
They are reasonable only sometimes (
express rationale behind choosing a certain approach, or
to stress out some important detail in the implementation),
but in general try to minimize using them.
Javadocs are useful, but keep them accurate.
Misleading comment is worse than no comment
If you write a comment, write about what is just next to it, not about the whole system around.
Only about what the function has control over. Otherwise it will soon become outdated, and therefore misleading.
No point in writing sth like / Returns the name. / getName().
Using HTML in comments makes them harder to be read in IDE - so where they are read the most.
Don't comment out code. Just remove.
it is in version control
Don't use closing brace comments.
Always try to explain yourself in code.
Use as explanation of intent.
Use as clarification of code.
Use as warning of consequences.
Create method names and informative variables instead of explaining the code with comments.
They should not be used to indicate who changed or why, for that already exists in versioning.
Last updated