Are Code Comments A Code Smell?

I've heard this being thrown around a bit, developers love talking about code smells. There is this myth perpetuating in most forms of programming that inline code comments are a code smell and a band-aid covering inadequately written code.

I disagree.

Comments should explain why, not how

I agree in the instance where code comments are used to explain how something works, that is indeed a code smell. If you have to write a comment explaining what is going on, it means the code you wrote isn't adhering to one or more sane development principles like improperly named variables and functions name for a start.

Explaining why is infinitely valuable, especially for anyone inheriting your codebase months or years down the track. If you move on from the company and you've written a piece of code (maybe you wrote an algorithm), while technically your code should be "clean", you sometimes need to elaborate on its intent.

An example from an application I am working on right now clearly highlights the "why" use-case for comments:

// If the following code is triggered, it means that websocket found in the common source library has failed and means that someone has broken something in the common library.

It doesn't explain how things are being done, it explains why this particular if statement and code inside of it is being triggered, due to the fact that something has broken in a separate library and codebase.

A fear of commenting, a broken generation

As a web developer, I can recall when we started to move away from using tables for markup and instead choosing to use DIV's and CSS floats/displays instead. It was a fierce anti-table campaign, blog posts decrying the use of tables emerged, the mantra that tables were bad started to spread.

The problem is, the whole point of this was to say don't use tables for markup, but at no point was the message meant to be: stop using tables entirely. And yet, this is what happened.

As new developers entered the industry, they were taught that tables were bad and you should avoid them. Developers had the statement, "tables are bad" drilled into them, tattoo'd onto their skin and added to the office water cooler.

Before too long, developers were using CSS and DIV's for everything, even situations where a table would be the better and recommended option were being avoided because developers were afraid to use them.

Eventually, we reached this fever pitch moment where developers were afraid to use tables and then things boiled over. The message changed from, "tables are evil" to "use tables for tabular data"

This is where we are at with code commenting. The message has become distorted, and as new developers enter the industry they'll be taught to believe that comments are evil and opt not to use them at all. Comments have value and will always have value.

They're only guides

This is one important piece of advice that I tell any developer I work with, especially a junior developer. These best practices and code smells you should avoid are to be used as a guide online, they're not hard rules you have to live and die by.

You should aim to write code that is easy to read, easy to test, has clear intentions and could be understood by a developer of any experience level. But there are instances where the purpose of the code is clear in how it works, but the story of why it needs to work that way sometimes needs to be explained.

Remember this saying: well written code is better than documentation.

Code smells are not errors

This is singlehandedly the biggest and most frustrating issue I have with the term "code smell".

Developers are being led to believe that a code smell is an error (or almost error), or something that needs to be fixed. It's right up there with the likes of the term "anti-pattern" another trope that developers love to wheel out when they're on their high-horses.

A code smell merely means that something might be wrong, that it might be unneeded or in need of improvement. Under no circumstances should a code smell ever assume to be an issue, because sometimes a code smell isn't one at all and at other times, it is.

So the next time someone even remotely implies that a code smell is this exact definitive conclusion term, you'll know that it isn't.

If the term code smell was French, it would translate back into English, "Something could be wrong here, you should take a look and see if it can be improved"

Image from Pixabay.