Every now and then, I find myself writing about a topic that's been written about (too?) many times in the past. Usually, this happens when I stumble across an old article that resonates with my current work.

In this case, however, I didn't stumble across an old article – I had to actively go out and find it, because I remembered exactly what I was looking for: I was recently asked about the worst programming advice I've ever received (or read).

I hate to call anything in the software development world "wrong", other than possibly code which doesn't compile. That said, I think the worst programming advice I've ever read (and in my opinion which borders on as close to "wrong" as you can get) comes from an article called, "Why You Shouldn't Comment (or Document) Code" and its obligatory follow-up article, "No Comment: Why Commenting Code Is Still a Bad Idea". For the record, I'm not going to name the author here, and he's definitely not the only one who holds this opinion.

While the author's arguments against comments are many, one of them looks something like this: "readers suggested that comments [provide] insight into what [...] programmers thought their code was doing. I don't care what those programmers thought their code was doing – I only care what their code actually does."

I would hope that to many developers, the problem with the above statement is pretty apparent. The statement is rooted in a sort of mistrust for the comments ("what the programmers thought"), but the fact remains that the author does of course care what the code actually does. That (dare I state the obvious) is exactly what a comment is for: "this is what my code does". It is quite frankly on the author if he doesn't want to trust the comments. I personally would much rather read comments and trust that in most cases they're correct versus have to – in the absence of a comment – trace through the call stack to watch exactly what the code does at every step of the process and to try to make sense of it (unless and until I had to).

I think at its simplest, the argument about coding without comments can be shown to be "wrong" (or at least ill-advised) by simply looking at how you as a developer have learned in the past. Whether via an instructor, a book (I'm still a fan of paper books), a written tutorial, a video tutorial – whatever – the fact is: you're never looking at just code. There is context around it. Granted, the snippets of code shown to you may even be devoid of comments, but there is always something or someone explaining some facet of the code to you: how it works, why it works, what the mindset behind the approach was.

You would never read a programming book or watch a programming video and expect it to consist of literally just 100% code. Ask yourself why this is the case, and you'll have your answer as to why comments in code are so important.

Code and context go hand in hand. When you see code in a book or video, you expect to learn a bit about how or why it's doing what it's doing. The same expectation should exist for a codebase.

There is human value and there is machine value, and this is the distinction that I think is really missing in most of these "anti-comments" arguments. The underlying tone here is that the only thing that matters is the code itself – that the compiler or interpreter can take it and ultimately execute it. Anything else is superfluous and just extra room for error and maintenance. This is the real gap.

Comments are a necessary bridge between human thought/intent and machine-executed code.

In a high-level language, something like:

may not need a comment. I'd even agree, of course, that this would be an example of a "bad" comment:

When you start getting closer and closer to the machine's level with the code, however, the importance of comments should be plainly obvious:

I don't know about you, but I'd personally be really thankful for that comment. Unless I happened to remember all of those registers and interrupts, I'd be searching through docs (anyone remember Ralf Brown's interrupt list?) for these details. I'll take the comment any day! And even if the comment were wrong and the code was actually setting 320x240 mode instead of 320x200, I'd still have more of a clue as to what the code was doing than I would without the comment.

In fact, it should be apparent that the further the code is from natural human language, the more important that comments become. This is also why commenting something like a complex calculation is critically important.

Some organizations have PR (pull request) policies that require comments be removed for the PR to be approved. Honestly, I find this crazy. Like everything else, being pragmatic and practical is always a balancing act, but I would much rather look at code that has a comment – even if the comment is just a block of old code – than no comment at all, especially if the code is complex.

Even the old code itself provides value here, whether on the intent, the thought process that was gone through to the get the code to its current state, etc.

In fairness, one thing that I am not a proponent of is what I call "chicken commenting". This is when a developer finds a block of code they think they need to change – but they're not quite sure – so they duplicate the block, comment out the original, and then poke changes at the code.

Doing so can almost be understandable at times. I once worked with a large VB6 project (which used .zip files for version control) that had gone through so many hands, no one really knew what the code did anymore, so to avoid breaking things, blocks of the original code were routinely commented out and duplicated to provide something to fall back to in the event that any changes made didn't work. Unfortunately, the commented-out code blocks were rarely removed, even when the changes worked. This I consider an inappropriate use of comments, especially when done to excess.

At the end of the day, however, like most everything else in software, it's all a balancing act. In the same way that I feel that making a blanket statement like "boolean parameters are evil" is rather arbitrary, I feel that saying that code shouldn't be commented or that comments shouldn't be in production, master-branch code is equally arbitrary.

There's generally an understanding that all code has bugs (even when it compiles, of course). With this in mind, avoiding comments simply because they're not checked/compiled doesn't make much sense. Successfully-compiling code only indicates lexical and semantic correctness; it says nothing about logical correctness. This is another bridge that comments help to provide: "Does the intent match the design?"

Source code is holistic, and trying to limit it to simply machine-operable instructions does no one any favors – especially the next developers in line who inherit that code. If you're not big on commenting your code, I'd encourage you to give it another shot. Your fellow devs – and maybe even your future self – will probably thank you for it.