When I learned to program, hardware and storage were scarce. It is imperative for the code to be tight and the speed of execution is and remains a first and foremost concern. Achieving this isn’t always easy and often requires some very sophisticated programming techniques
If there was ever a time or place to demand comments, a clever or complicated code sequence is it. Many books and courses will tell you to comment on your code and many experienced programmers do an excellent job of doing so. Writing clear and useful comments is as much a skill as it is a discipline.
The coding style where indentation, line length (80 characters maximum), avoiding the use of global variables and writing single purpose functions also help to understand and debug the code. Make your comments relevant and don’t restate what should already be clear.
Some will argue that good well-written code is self-documenting although my experience strongly suggests otherwise. Well-worded variable names are helpful; however, their intended purpose may not always be clear. Functions, subroutines, or classes may also have well-defined names yet arguments and/or parameters and results may not be.
I recently found myself having to debug a program I wrote over a year ago. The application was working on all machines but one. I learned that the client replaced the computer with an old legacy system. Fortunately, I have been working with PC’s for more years than I care to admit and understand what was happening and why.
Needless to say, were it not for the comments, fixing the issue in the actual code would’ve been a daunting task otherwise. The very sections of code that were to occupy my time were cause for previous visits. The comments clearly describe what the code sequence is supposed to do and the potential caveats to avoid.
Good Meaningful Comments
All of my code modules have an opening comment block that, aside from the author(s), date created, purpose, and revision, provide specific details regarding the methods/techniques and how they are used in the code to follow. Even the method of versioning the module is clearly outlined.
Complete history with version/revision number, date, and description of the changes accompanies the opening block. The specific changes are dated and documented in the revised code segments as well. Dating the changes in my code serves as a frame of reference and allows me to better recall the events that triggered the changes in the first place.
/* System.out.println(“Don’t use block comments to block out code\n”); */Rule of Thumb
A good “rule of thumb” is to provide sufficient comments to reteach yourself or to teach others what the code is supposed to do. I also provide ample warnings and advise of possible side effects that code changes may introduce.
If there is ever a place to serve yourself best in your coding skills, it’s in the comments. Everything that appears fresh today will be everything but fresh a year from now. A well-documented program requires focus and discipline, but the effort will make the debugging process so much easier when you visit your work in the near or distant future.
Until next time, STAY lean!
