DEV Community

Discussion on: Comments Are The Only "Code Smell"

Collapse
 
darkwiiplayer profile image
𒎏Wii 🏳️‍⚧️

OMG! Your variables are so longggg! Everything's so verbose! There's no way that I want to code like this!

I've always found that way of thinking very childish. Code is read way more often than typed, so choosing variable names that are shorter to type is incredibly short-sighted.

It's not that I don't often find myself thinking that. But I often find myself thinking "damn I want a siesta right now" yet I don't just start sleeping in the office.

Comments should never (unless you're hacking bits in an OS kernel or something) explain the code. They should explain design choices:

  • Domain-specific decisions
  • Complicated optimization choices
  • Test and benchmark results that influenced the design
  • References to resources explaining rarely used abstractions
  • Bugs in external software that need to be considered

So overall I'd say I pretty much agree with the article, though I find the title somewhat clickbaity. There's so many valid uses for comments that calling them a "code smell" is really stretching the expression a lot.

Collapse
 
bytebodger profile image
Adam Nathaniel Davis

So overall I'd say I pretty much agree with the article, though I find the title somewhat clickbaity. There's so many valid uses for comments that calling them a "code smell" is really stretching the expression a lot.

Guilty as charged! But I made a point to illustrate exactly where comments are useful (critical, even). And my examples pretty much line up perfectly with yours.

And with regard to those who complain about variable name lengths, I also find their arguments to frequently be arbitrary. In other words, they complain about the length of the variables you've chosen, but when they decide to use a longer naming convention, it's totally "OK".

Collapse
 
v6 profile image
🦄N B🛡

Code is read way more often than typed

This has so many underrated implications.