Thoughts on Commenting in Code

Posted: 2/16/2024

I think that it is time for me to tackle some of the most deeply controversial topics in coding/computer science. Where better a place to start than commenting code? When should comments be written and what should they indicate? Exactly how much should they indicate? I am going to dive into my stance on these divisive issues.

First, a little bit of my history in this area. I am going to use really life examples from my archives do demonstrate along the way. In high school, us students learned that most lines need a comment. I believe that the stated rational was that it gave a way for future coders to understand our work. Realistically, I suspect that it was for the teacher to determine whether we knew what we were doing, and to make it easier to sus out cheaters. This led to such insightful comments as this:

It also made for a tedious experience. This approach effectively leads to writing every single line of code twice.

When I got to university, the instructors taught us a different method. It did not matter what a unit of code did, we only needed to describe what inputs it accepted, what it did with those inputs, and what it returned. I apologize deeply for introducing you to scheme in this example. The approach is more concise, but occasionally felt like there was more of a story being written than an application.

Following my time in university, I moved on to a different computer programming program at Seneca. A third philosophy emerged there. Only major units of code and variable declarations needed comments. This was a middle ground between the two previous approaches. These comments focused more on what the code did as opposed to the individual nuances of implementation from high school and the big picture of university.

Once I got into my professional coding life, philosophy number four showed up. All the expert wizard coders on YouTube seemed to feel that if the code needed commenting, there was something wrong with the code. It fell along the same lines as the trading card game adage “reading the card explains the card” (Which also is not always true, but we will get into that). To summarize, the code should be clear enough on its own, that comments are only an extra burden to maintain.

That brings us to where my feelings landed. As with many things in life, the truth is somewhere in between. I want to go through the disadvantages of each method before revealing my current mindset.

Every single line is a waste of time when working under the assumption that whoever working with the code in the future has at least a little knowledge of coding. It can also act as a conduit for terrible code. Looking back at my past work. A lot of lazy or bad implementations can be explained away with a comment on every line.

Function descriptions have similar issues. They do not give any agency to the quality of the implementations themselves. They also give away unnecessary or redundant information. Ultimately the consumer of the function has no need to know the implementation details. I hope to blog through the entirety of SOLID at some point, but for now, I will leave it at that. Additionally, someone who is working within the function or analyzing the implementation likely does not want to go back to the function description to understand what is going on. The final disadvantage that I see in this approach is that sometimes, a function might not need a description to be explained. For example, if a function is titled isEven and accepts an integer, what would anyone expect it to do beyond returning true or false base on the integer’s divisibility by two?

The college methodology falls closer to what makes sense for me. It still has its issues though. There still is not a focus on making sure that the code itself is readable. Blocks and variables are a great starting point, but they feel like checkpoints. They do not dictate that the path between them be smooth.

Finally, the just let the code do the talking approach has its share of downfalls. The approach assumes that whoever is using the code can see the code or does not mind sorting through source code to see what it is that the function that they are consuming is doing. It also works under the assumption that code can always be written in a clean manner, and that the approach always makes sense from a time perspective. Sometimes there are just oddities that need descriptions, and in the real world, time is money. Code that will likely never be touched again cannot justify three to four rounds of refactoring to make it perfect for generations to come.

That brings me to my current philosophy. Function comments (Javadocs, PHPdocs, JSdocs, etc.) are a must for most functions. Modern IDEs are too good at their jobs to justify leaving documentation blank. It saves an immense amount of time being able to see a description of what the function does, what it needs, and what it returns immediately. This is especially true for weakly typed and sort of typed languages like JavaScript and PHP. In the case of PHP it is also the case that since type hints where added to the language somewhat recently, there is also a lot of legacy code with vague unions, an associative array, or just “mixed” as the specified return types. The comments describing the actual return value are incredibly beneficial.

This also applies to type definitions in TypeScript. Adding the documentation to the fields in a custom type adds so much more clarity to the intent of those fields than even the longest of variable names would.

With that being said, the downsides I mentioned in relation to the “just let the code do the talking” method still apply. It has been said before that premature optimization is the root of all evil, and that also means that not everything will end up being optimized, and in turn not everything will be written clearly enough to explain itself. Sometimes the code itself needs extra documentation built in. Time may be limited, and sometimes there just is not a clear way to indicate what is going on.

A philosophy that I look at the world with more generally is “very few things are ever truly black and white”. Comments are a relatively trivial example compared to the big picture, but the statement shines right through. There are always nuances and trade-offs to whichever approach you take.