DEV Community


Discussion on: Comments Are The Only "Code Smell"

ecyrbe profile image
ecyrbe • Edited

Hi Adam,

Again, nicely written article.

I would add that using long names to explain your code should be the norm. But good naming is an art.

The team should refuse to validate functional code if there are some naming issues.
Code is not just the instructions you give to the machine. It's also the way you inform the future maintainers of your code what it does. It's your communication tool to the future YOU that will read this code two years from now.

The issue with comments is that they become obsolete when the code evolves.
And the only thing that evolves with your code is your everyone should keep in mind that code that works and have no bugs is not sufficient.

You should strive to produce self documented code. And most of the time self documenting code, means long names that convey meaningfull information.

bytebodger profile image
Adam Nathaniel Davis Author

I agree with all of this. And in my article, I completely forgot to point out the tendency of comments to become stale and unrepresentative of the very code in which they're embedded. I particularly enjoy this statement:

And the only thing that evolves with your code is your code