Code Comments

Love them or hate them, we can make comments useful

There is a game I used to play growing up called Clue. The premise was simple. You went around a board to different rooms to deduce who murdered the game's victim, where the crime took place, and which weapon was used.

Other than Risk, it was my favorite game as a child. While you could get lucky and just guess the combination early on, the real fun was whittling down the mystery through the clues you gathered. I could put on my detective hat on for an afternoon or evening as I unraveled many paths to get to the truth.

Sometimes reviewing other people’s code can feel the same way, but without the fun. It was not often, but there were instances when I would have to review code because someone was out of the office or I had to integrate to other systems (in the days before microservices and well structured API’s). The most anxiety producing times however were the projects that involved migrating older code bases to newer platforms. I would have to go into full on forensic crime scene investigator mode on these codebases.

Understanding code that is not yours can make you feel as productive as staring at a wall. Some developers that can just look at code once and decipher it in minutes. That was not me however, so I inched my way through code one painful line at a time.

I have what I called the “Five Circles of Code Despair”. The first was if documentation was available. This only happened in alternative universes though, so my real first level was the person that wrote said code if they were still alive and accessible. The second level was when the code was somewhat understandable, which was rarely the case. The third was help from other developers. The fourth was me staring at a rubber duck. Then the deepest circle of weeping and gnashing of teeth was reached when I had to rely on unpacking code artifacts for clues.

Code artifacts are the things that are produced in the process of developing and deploying code. This includes design documents, data models, workflow diagrams, test plans, configuration scripts, commit logs, etc. As one Stack Overflow answer noted, artifacts are, “like an archaeological site, anything that is created could be an artifact.”

Comments are one of those artifacts. You could debate this, since comments live in that grey area of being derivate and separate of code, but also tightly coupled to code. They get checked in as code and are only accessible through reading the code, but do not serve any purpose another than to annotate the thoughts, mental pauses, and mad ravings of the coders that added them.

The types of comments that I would usually find would definitely fall in the category of mad ravings. My favorite were the comments that restated the obvious, like one program I reviewed where all SQL statements had comments that stated GET, UPDATE, or DELETE. And I cannot recall how many times I have seen counters with the comment, “Increase i by one”.

A quick Internet search, unearthed a treasure trove of comments, so here are some of the most inane, maddening, and hilarious comments pulled from code:

  • /*Added because someone asked me to add it*/

  • // Do not remove this comment else compilation will fail.

  • // Undocumented

  • // [A piece of nasty code here]

  • // remember to comment code

  • /* our second do loop */

  • // Don't know why we have to do this

  • // it's a kind of magic (number)

  • //Whoa, now that's a big if condition.

  • /* this is a hack.

  • return 0; // Return value does not matter

  • # All your space are belong to perl

  • //@TODO: Rewrite this, it sucks. Seriously.

  • // yes, this is going to break in 2089, but one, I'll be dead, and two, we really ought to be using a different system by then

  • /*  * Replaces with spaces  * the braces in cases  * where braces in places  * cause stasis.**/

Going by this list, you would think most developers are either amateur comedians or have pent up passive aggressive tendencies. The reality however is that most of us have no idea what to even put for comments. I was always was told that commenting code was important, but never what those comments should be. This is why I rarely, if ever, added comments to my code.

A recent tweet however made me rethink the value of comments and why they can and should be a valuable tool in the developer toolkit:

I am not sure I am on board with his last thought, but I fully agree with the sentiment of how comments should be used. If you examine the history of code comments, they were a necessity in an era when compute was expensive. Variable names were obscure, hacks were employed to save memory, and code often looked like spaghetti. This led to the creation of two types of comments; block comments often seen on the beginning of code that are more akin to documentation, and in-line comments that offer specific hints about that particular line of code.

What did not evolve was what exactly we put in those comments. There are many opinions across developer communities that are quite valid that state code comments should not be necessary. They believe that all code should be self-documenting. The other feeling is that comments add complexity:

“Code never lies, comments sometimes do” – Ron Jeffries

Ron Jeffries is one of the three founders of the Extreme Programming, so I do not take his comments lightly (pun intended). If you update, fix, or refactor the code, how often are we bothering to update the comments? If the comments are not updated, it can leave developers with two views of the “truth”.

I also balance this perspective though with another oft-cited quote about coding:

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler

Comments are still valuable for us humans for making sense of code. Block comments often act as documentation for overall thoughts about a large code blocks. Most IDE’s can manage this meta data and operate on these blocks in ways that guide developers. This creates code intelligence, and we are beginning to see more and more AI driven developer solutions that can surface and mold this meta data for helping developers understand the why behind the code.

The in-line comments are also valuable however as code smells. You will not always know the best or more optimal way to craft a piece of code. Either you are running out of time, you are grappling with unknowns and dependencies, or the rubber duck is failing you. Comments are indicators then, a developer mental note, that can be clues for other developers that need to review the code later on. They use these “smells” as clues to decipher your thinking at the time.

The best comments though will always be the code itself. Next week I will explore how teams can build a practice of writing self-explanatory code and then lay the foundation for fostering a culture of documentation.

Till then, I would love to hear your stories about code comments; the funny, the frustrating, and the flagrant fouls. How are you using or not using code comments in your code or the code of your team?

Mark Birch, Editor & Founder of DEV.BIZ.OPS

Leave a comment


Want to learn more about DEVBIZOPS and read more hot takes about IT, technology, and working smarter. Receive our weekly newsletter by signing up to our Substack!