To Comment or Not to Comment. That is the Question

Perhaps if Shakespeare lived now and was a programmer, he would have written Hamlet’s soliloquy, “To comment or not to comment? That is the question – whether ‘tis nobler to have your code understood by others and not be called to explain old code, or to be tied to a program for eternity…”. This parody of a Shakespeare quote might be funny for only the hard-core programmers, or maintenance individuals who must support computer systems 24X7, but it is telling in many ways. Commenting is a contentious topic for many developers. I have seen some programmers believe that comments are as important as the code itself. I have also seen the opposite where developers believe that their code is self-commenting and comments are not necessary. The actual answer is somewhere between those two with a leaning towards more comments.?

According to Pascarella, Bruntink, & Bacchelli (2019) comments make code more readable and maintainable. Comments assist the developer who is reading the code to understand what the purpose and function of that code. Comments are not compiled into the executable code. The programmer can create 125 pages of comments in a program with 4 lines only the 4 lines of code are compiled into the executable. The comments have no effect on the execution of the program. The developers can add all the supporting documentation they want into the code to assist the maintainers to understand the code. I have been in development and support for over 25 years. One of my favorite quotes is by John Woods, “Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live”.?

I have had the call at 2:00 in the morning to fix broken code several times in my over 25-year career. I am sure that I will have the call many more times before I retire. I did not write most of the applications I had to correct and review, but I had to correct the problem, nonetheless. A great deal of code written outlives and outlasts the developer who created it. Developers move on to different teams, companies, jobs, get promoted, and retire. When the developer moves away from the system that they helped create, the supporting team loses their “tribal knowledge” which is the experienced gained while creating the initial system and troubleshooting (Yueton, Shahhosseini, Badar, Foster, & Dean, 2016). Leaving the system with proper comments and documentation is not only useful, but it is polite.?

There are many excuses for developers to not add comments to their code. The first reason is laziness. Some programmers think fast, write fast, and get into a groove to create some interesting, fascinating, and useful code. The laziness part is that the developer spends 7 hours creating this masterpiece of technology and going back to document is not only difficult and frustrating, but it is annoyingly difficult. In most cases, being lazy about adding comments at the end of the day is not done with malicious. Laziness is just being lazy. Another reason for not commenting code is job security. This is a dark view of your coworkers, but it is accurate. A common statement among developers is if it was hard to develop then it should be hard to understand. I have run into that specific situation in my many years of being an IT resource. The job security reason leads into the idea of false pride in making complex code. If the programmer always must be consulted on what the program does then the false pride and job security allows the programmer to pretend that they are more important than they are. The worst group of excuses is combined into one I call commenting ignorance. The commenting ignorance list contains the following: comments take up too much space, comments make the code too hard to read, and comments make the executable code too large. Commenting ignorance is the worst type of excuses a developer can use. The best way to avoid these excuses is to make commenting easier.?

Using an integrated development environment (IDE) can assist in making comments easier to create. Some IDEs such as IntelliJ have templates that can be used to set formats of functions which can include comments. Usage of templates can remind the developer to add certain parts of a function to include comments. There are also standards that can be created along with using the templates created in an IDE. Whether the programmer follows through with the format is left to the developer and the coding standards for the organization.

Essentially, comments are important. They should not be the main reason for the code, but they should go hand in hand with good coding practices. Should the comments have a five-paragraph essay per module? Should there be a comment free module? Does self-commenting code exist? The answers respectively are no, no, and no. What developers should be writing is somewhere in between. If you, as a programmer, starts to read the code you created even a day ago and are confused, then maybe it is time to start commenting.?

References

Pascarella, L., Bruntink, M. & Bacchelli, A. Classifying code comments in Java software systems. Empir Software Eng 24, 1499–1537 (2019).?https://doi.org/10.1007/s10664-019-09694-w

Yuetong Lin, A. M. Shahhosseini, M. A. Badar, T. Foster and J. Dean, "A concept map-based cognitive framework for acquiring expert knowledge in industrial environment," 2016 IEEE Frontiers in Education Conference (FIE), 2016, pp. 1-5, doi: 10.1109/FIE.2016.7757702.