Only comment what needs to be commented
"If you comment everything, people won't read them."
"As soon as one comment is incorrect, the result will be ignored."
These are two comments I heard recently referring to code comments.
If there are too many comments, people will get lost in the information. They won't be able to differentiate boilerplate comments from valuable ones, and as soon as one comment is incorrect, people will assume that others could likely be incorrect too and ignore them.
A solution to these is to only comment what needs to be commented.
Only write comments that add value, and if there are fewer comments, they are easier to read and maintain - making it more likely they will be incorrect.
This is an example from an open source pull request:
/**
* An interface for field access override.
*/
interface FieldAccessOverrideInterface {
In my opinion, this doesn't add any value or additional context as it repeats what's already there.
Something I put in my project configuration files is to tweak the coding standards to not check, for example, for class and method docblocks - allowing me to add them where I want and where I think they're needed and add value.
I think this is better than having comments everywhere, and I can focus on the ones that matter.
- Oliver
