7th December 2025
Programmers talk a lot about smells. Smells are an indicator that something is wrong, and comments are often described as 'smelly'. Some programmers think that adding comments to your code means that it's poorly written - it should be clear from reading the code what it is doing. While this might be true, it also misses an important point; we don't only need to know what your code is doing, but why.
I apologize for such a long letter - I didn't have time to write a short one.
- Various
Code is read far more than it is written, so we should work to make it as easy to read as possible. Like well-written prose, you shouldn't need to re-read passages to understand what is being communicated. Well-written code is easy to read and understand, and code that is easy to read and understand is easy to change. Poorly written code is difficult to change, because it's unclear how the changes you are making will affect its behaviour.
One programming mantra is; "make it work, then make it good". Unfortunately, many engineers stop after step one. It takes time and effort to turn working code into good code. If you don't have the time, or motivation, to turn your working code into good code, comments offer a short-cut to communicate the intention with whoever comes to read or adjust the code in the future (which may well be you).
This isn't always the fault of the programmer. They may want to take the time to improve the implementation, but outside pressure may prevent them. At work, we store and handle money a few different ways in different areas of our application. Sometimes as floats, sometimes as strings and others times as integers of cents. This is typical technical debt. Ideally, they would all be refactored to use the same implementation, but time and priorities are against it. Without knowing this, it could be confusing to come across amounts being multiplied and divided by 100, especially as it's only done in one small corner of the application. This is why there are comments to mention the amounts being stored as cents, to quickly avoid any confusion. The comments don't say what is happening, but why.
In his seminal book Refactoring, Kent Beck compares comments to deodorant - used to mask the rotten smell of bad code. He's more forgiving about comments that describe why something is being done, at least for "forgetful modifiers". The problem is; all modifiers are forgetful.
... comments often are used as a deodorant. It's surprising how often you look at thickly commented code and notice that the comments are there because the code is bad.
...
A comment is a good place to say why you did something. This kind of information helps future modifiers, especially forgetful ones.
- Kent Beck
Another place where we can provide context is in commit messages. Telling me what you have done in a commit is useless, I can see that from the diff. Telling me why you have made a particular change, the reasoning and decisions that went into it, is going to be a lot more useful six months down the line than WIP.
So what do we do when we come to refactor code, but don't know why a particular implementation was chosen? Hopefully, comments or commit messages provide enough context around the decisions that were made at the time. If not, you might be able to ask the colleague that wrote it what their intentions were and hope that it was recent enough for them to remember. If the code was written by AI, then the reasoning behind it was never there in the first place. Of course, the AI will be perfectly happy to bullshit you about what its thought process was, but the nature of it means you're not getting the truth. AI doesn't weigh the pros and cons of various implementations and choose the one that best fits the business domain, it vomits out some close approximation of the implementation that appears most frequently in its training data.
Comments and commit messages are best used to provide context. Why was a particular implementation chosen? Why did you use this endpoint rather than the alternative? Explicit knowledge is contained in the code, implicit knowledge is lost in the implementation. Code can't tell you why these things are happening, but comments and commit messages can. Do your future self, as well as your colleagues, a favour and consider whether understanding why something is being done a particular way will be useful when reviewing or refactoring in the future. Not only is it something your colleagues can't extract from the code itself, I can also guarantee that you won't remember the reason six months from now.
