Comments should be part of code review, having at least two pairs of eyes on comments is crucial. Something that’s obvious to one person maybe isn’t so obvious to another. Writing good comments is as hard or harder than writing good code, so having it checked for mistakes and quality is a must
Comments aren’t the actual documentation and aren’t a reason not to write documentation to go along with your code. Often I see larger projects where each class and function is documented in comments, but the big picture and the how and why of the overall structure is completely missing. Remember that in the real world you often have a lot of folk that need to understand how the code works, who aren’t programmers themselves. They can’t read the code or don’t have access to the code. Writing documentation is still important.
Please for the love of god when you change code, check if the comments need to be updated as well. Not just around the immediate area, but also the entire file/class and related files. I’ve worked on large codebases before with a high wtf factor and having the code do something different to or even opposite the comments is a nightmare. I’d rather have no comments than wrong comments.
This is a notoriously bad book. If you read the part about comments (which I don’t know about, and am willing to accept is good) make sure to skip everything else because Robert Martin is a fraud.
Good advice, just to add to this:
This is a notoriously bad book. If you read the part about comments (which I don’t know about, and am willing to accept is good) make sure to skip everything else because Robert Martin is a fraud.
Agreed, removed
I’ve seen cases of outdated comments in the same line of code it’s describing. People suck at maintaining comments.