To comment, or not to comment, that is the question. (Part 1 - Downside of commenting)
“Commenting is a must”
As prospective programmers, we were told to comment our codes thoroughly and our comments were often graded for its quality as much as the quality of the code itself. Professors say that well-written comments are a sign of professionalism and represent the validity of codes themselves. Donald Knuth — the famous creator of TeX and father of the analysis of algorithms — even advocated literate programming which suggests programs to be written in human language rather than computer compilers.
From my past encounters with the great minds who’ve influenced me in my knowledge of developing, I always thought that commenting is a “must”.
Commenting in real life: “Commenting?? hmmmm…”
Whether you are publishing a web page, devising an elegant search algorithm or developing a real-time web application, you often find yourself in battle against resources: time, man power, efforts and on. Elegant, efficient and effective programming — I call it 3E Program because I like to come up with new abbreviations and feel smart — is useless when battling against time because an “okay” working program is better than a “perfectly designed” but not-working program. I often employ this attitude and settle with rather imperfect and not-so-elegant results, however, there are many programmers who constantly strive to achieve perfection. As I just mentioned, I tend to lean toward “okay” working programs rather than the other option, and I am sure that you can easily picture the quality of the comments of my codes. My comments often merely exist as I write in phrases and words that only make sense at the time of coding. It is like an ancient language that only a person from the past (myself in hurry) can understand. Because of this, I tend leave commenting out of my codes since it practically becomes useless in the future.
Everyone is probably well aware that commenting can be cumbersome and regarded unnecessary. Code itself becomes understandable and literate when coders choose straightforward names for variables and functions and write in succinct and well-formatted fashion. This happens because coders trained themselves to think like a computer for so long that programming language became their mother tongue, and codes naturally became simple and understandable. Trying to explain what is already self-explanatory would be similar to solving complexity by adding more complexity. The following points are “anti-comment points” that I gathered over several passionate online discussions.
Anti-Comment Point 1: Commenting is cumbersome
The biggest downside of commenting is that it requires additional time and effort. Developers by nature always look for the opportunity to optimize. What developers do — AI, machine learning, graphic rendering, VR, AR and every other things — they do it to optimize and make life better. When your job is to optimize things and when efficiency and elegance is the epitome of programming, commenting or documenting — also known as developers’ paperwork — ought to be disregarded.
In addition to writing comments being a pain in the southern region, maintaining and updating comments can potentially become an even greater pain in the ass. When associated codes are changed, comments should be changed as well because comments without update will most likely be misleading or perhaps better without.
Also, considering how rapidly codes change these days, maintaining comments can create frequent and repeated overhead. Close your eyes for a moment and think of the many short-lived revisions and implementations you wrote. Now imagine all the short-lived revisions require commenting as well.
Anti-Comment Point 2: Commenting is not for the actual coder
It is natural that people grow reluctant to do work that does not provide direct benefit to themselves. Commenting often is one of those things that does nothing for us. Commenting isn’t for the author of the code. Rather, it is often for developers and designers who have very small experience with the code; hence lack of understanding. Since the benefit to myself is distant and indirect — the only direct benefit might be the future “me in hurry” — it tends to be omitted. Codes are better without comments than having insubstantial subpar comments.
Anti-Comment Point 3: Requires developers to have good writing skill
The Donald Knuth — father of literate programming — once said in his interview with Andrew Binstock that literate programming requires programmers to be good at both writing and programming:
“ … a small percentage of the world’s population is good at programming, and a small percentage is good at writing; apparently I am asking everybody to be in both subsets.”
Donald Knuth
I’m well aware of the fact that commenting is only a small portion of literate programming. However, they share similarities as they both require writing more than ordinary coding convention — more codes and not so much English. Programmers are professionals in writing codes in programming language not in English. Writing things in English is never included in job specifications for programmers. Asking a New Yorker to speak in southern accent is doable. Asking him to speak Chinese is unreasonable.
Also, when writing comments becomes a convention, we also run into the problem of language barrier. I’ve been told numerously that almost all non-English speaking developers don’t have trouble with reading English. Writing English, however, is different. Conversing with others and expressing opinions in English is quite demanding to non-English speakers and may eventually hinder them from contributing their thoughts.
My Stance
Despite what I’ve written above, I actually believe that benefits of commenting outweighs the above mentioned downsides. To me commenting is like a bad tasting cough syrup. You know it is going to help you, but you just don’t want to do it because it tastes bad, or you just don’t want it because your mom used to force it on you. (Just like some clients/boss force use to comment)
Well everything is double sided in life, and I firmly believe commenting has its advantages which I will talk about in my upcoming post.
I would like to finish it up with one of my favorite quotes regarding comments.
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
Thanks for reading this article and stay tuned for my upcoming post where I will talking about benefits of comments. Be sure to send me ❤ by clicking ❤ below to recommend this article if you found it helpful. It means a lot to me.
