Commenting code is one topic, that until recently, I hadn’t known was such a widely debated issue in the programming world. It was something taught to me from day one in Computer Science at the University of Northern Iowa. Recently, my workplace posted a simple question on an open-discussion white board. “Should we comment our code?” The plethora of anonymous comments was certainly enough to pique my interest. According to the discussion, hardly anyone could agree on this question. While many people argued over how much to comment and why, there was an almost equal number of people arguing that no comments are needed. The answer to this question is YES, we should comment our code, and I will explain why.
First, let’s start with why this has become a topic in the computing world. The advancement of computer programming methods, compilers, and high-level languages, has brought this fundamental question into the spotlight. Our capabilities to design and code programs has greatly advanced. We are now able to reliably use English-like language to write programs. C, C++, Java, and Python are just a few of the many new programming languages that help us to do this. The misconception occurs when we start to think that because we use these languages, that we can also communicate in the same fashion that we would when writing a manual or book. I see a lot of young (and some experienced) programmers who think eloquent and simple code is enough to be understood without comments.
To understand why we should comment, we first need to understand the purpose of comments. Admittedly, even I didn’t have a full understanding of “good” commenting practices before I began working for someone on large projects. According to expert Peter Vogel, in his article “Why You Shouldn’t Comment (or Document) Code”, comments are meant to explain “why”, not “how”. It is very easy for a developer to feel the need to comment every variable and operation that they code. If this is the case, then I would agree that commenting is a bad idea. Over-commenting is as bad as under-commenting. With too much information to filter, the important things become impossible to communicate.
Comments should help describe design choices. A new programmer should be able to understand what your program does without digging into the code. Properly commented code can tell you what things do and what you should expect when they do them. To think that this sort of information should be gleaned by reading the “simple and eloquent” code is just not realistic. This would be like asking someone to figure out how to operate a car by opening up the hood and figuring out how every little piece works together.
To put it another way, think of the programs and functions you write as a product. When someone “buys” it, they want to know only enough to allow them to use it. People buying a new cell phone want to know what it can do, not how the phone does it. Whether it be in a larger program, or stand-alone, they do not need to know what’s under the hood. Sure, some people may be interested in the “how”, but it is not necessary to understand internet protocol in order to use the phones browser.
I’d like to mention that comments in graphical programming languages, such as LabVIEW, should be treated in the same fashion. Being a user of such a language myself, I can see the appeal of thinking that, “Graphical programs can show intent and design much easier than text-based languages!” I can tell you first-hand, that what you think is obvious to you in your programming, is not always the case for someone else. Even current graphical languages are limited in what they can convey about ideas and architecture. This key problem presents one of the largest hurdles developers must deal with. Turning an abstract concept or idea into a coded program can be challenging. Many times, it is difficult to even explain it comprehensively to another person.
In summary, “good” commenting is good; “bad” commenting is bad. Be sure that what you are telling someone about your code is actually conveying information about “why” or “what” and not “how”. Nobody wants to interpret your program line-by-line, and nobody wants to read a book to understand your code.
