The truth is, you should never restate your implementation in comments. That, in fact, is almost always what proponents of this "wisdom" will cite!
However, while your implementation and naming should "self-comment" what the code is doing, it cannot explain why you did it, and more often than not, it fails to explain the abstract goal (or business logic). That's what comments are for: describe WHY, not WHAT.
One of our team's accepted code review standards is that comments should not need to be refactored when code is refactored. Keeps comments focused on the 'why', not 'what'.
Not a bad rule of thumb (keeps it language agnostic), although I don't know that it's altogether avoidable. In any case, if the two ever do fall out of sync, both should be carefully reviewed, as that's usually a signal there's a logic bug therein.
I completely agree. I work for a company that makes software for Dutch healthcare providers. A lot of financial processing which we automate is based on legal standards. When implementing these rules we always add a comment pointing to the legal documents that it implements. This saves a lot of "why did you do this" questions.
That's the kind of comment I write these days. I'll go the extra mile if a weird hack is needed (e.g., to circumvent a bug in a framework or library, stuff like that). Throw in the best names I can come of with for classes, methods, properties, variables, etc.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
"Never comment your code."
The truth is, you should never restate your implementation in comments. That, in fact, is almost always what proponents of this "wisdom" will cite!
However, while your implementation and naming should "self-comment" what the code is doing, it cannot explain why you did it, and more often than not, it fails to explain the abstract goal (or business logic). That's what comments are for: describe WHY, not WHAT.
One of our team's accepted code review standards is that comments should not need to be refactored when code is refactored. Keeps comments focused on the 'why', not 'what'.
Not a bad rule of thumb (keeps it language agnostic), although I don't know that it's altogether avoidable. In any case, if the two ever do fall out of sync, both should be carefully reviewed, as that's usually a signal there's a logic bug therein.
One of my favourite things in Go is the enforcement of good comments as documentation by the language.
I completely agree. I work for a company that makes software for Dutch healthcare providers. A lot of financial processing which we automate is based on legal standards. When implementing these rules we always add a comment pointing to the legal documents that it implements. This saves a lot of "why did you do this" questions.
That's the kind of comment I write these days. I'll go the extra mile if a weird hack is needed (e.g., to circumvent a bug in a framework or library, stuff like that). Throw in the best names I can come of with for classes, methods, properties, variables, etc.