DEV Community

Discussion on: What conventional wisdom in software is wrong?

codemouse92 profile image
Jason C. McDonald

"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.

thompcd profile image
Corey Thompson

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'.

codemouse92 profile image
Jason C. McDonald • Edited on

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.

gypsydave5 profile image
David Wickes

One of my favourite things in Go is the enforcement of good comments as documentation by the language.

bjornhollander profile image
BjornHollander • Edited on

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.

metalmikester profile image
Michel Renaud

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.