I’ve been thinking about the whole Comments-as-a-code-smell argument for a very long time. When I first heard this idea, I was in the comments are definitely needed side of the argument.

“Who could hate comments so much that they would label them as a code smell?” I thought.

Well, I had an epiphany the other day.

I’ve never seen a block of code that actually needed a comment. Ever.

If you have a section of code that feels too complex, instead of adding a comment do any/all of the following and you can, in almost every case, reduce the need for comments by 100%:

1. add a sourcecontrol commit comment
2. do a simple refactor (Compose Method ftw people),
3. use more descriptive variable/function/class/whatever names.

If you do all of these things and the code you are working on still seems too complex, you may have bigger problems with your overall architecture/design and adding a comment isn’t going to help. In this case it’s time to go back to the drawing board.

Also, everytime you commit a changeset into sourcecontrol that contains a section of code commented out god kills a kitten. Please think of the kittens.

code · code-style · opinionated · Programming