Essential Comments

As with good code, good comments should be readable, effective, and easily maintained. Essential comments should speak to other programmers no matter their skill level or purpose at the moment they encounter them since program maintenance may not require modifications to the areas where essential comments exist. The ultimate essential comment is a self-documenting program. What better language to speak to a programmer with?

Languages like RPG IV, C/C++, Java/JavaScript, and CL fulfill the self-documenting idea very well. True, RPG IV, C++, and Java can be coded with a complexity that belies understanding. But, we're talking good coding here! Complex code that works is no better than simple code that works and is understood by all. Is a program devalued by extra lines of code if the program's purpose is made clearer? Not at all. In fact, a well-written program should be discernible to any programmer who has a basic knowledge of language concepts and operation codes. If a program is too complex, then the next programmer may have a challenge deciphering it.

Such programs can be referred to as self-commenting programs. And why not? The programs themselves make commentary on their intent. Figure 1 offers guidelines for self-commenting programs.

Figure 1: Self-Commenting Do's and Don't's

The other essential comment type is the warning or caution. These comments tell the programmer "Touch this line of code, and you'll be sorry!" or "The code below is good until...". Set aside the idea that at least the last statement speaks to bad programming practices. The biggest problem with warnings is something that it shares with nonessential comments: difficult maintenance. Stick a line of code in the wrong place, and we lose track of what the warning was really meant for. Even worse, what if the code is updated but someone forgets to remove the comment? Avoid maintenance nightmares by avoiding warnings if possible. I only include this category of comments under the label "essential" because once they are in place, the programs may live or die on the basis of maintaining these comments (unfortunately). Self-commenting programs can be better than built-in comment structures because proper program maintenance will "speak" to the programmer, and the comments will move with the program. Figure 2 offers some guidelines for writing warning comments.

Figure 2: Warning Do's and Don't's

Self-commenting programs may have warning messages, but they should be kept to a minimum, and proper coding should minimize the need for warnings. Whenever possible, handle "time bomb" types of code with a special file or data structure that determines when to use what. Use APIs, conditional compiler directives, or other methods to aid in other situations, such as determining what to do when in batch mode or interactive mode. In fact, taking the time to find program alternatives for warning comments may likely be a useful mechanism in the future (i.e., the "time bomb" file could be used for other purposes if it is structured properly).

Nonessential Comments

My feelings about these comments are pretty well summarized in the name I give them: nonessential. I divide nonessential comments into three categories: templates, general notes, and cosmetics. Don't get me wrong about my "nonessential" title. While such comments may not sustain the life of the program, they can be aids to programmers. Don't discount their usefulness, but don't feel that you're doing other programmers a favor if you don't include essential comments with your nonessential comments.

A template, when handled properly, can be a low-maintenance standard comment that defines the program on its own. For example, whenever I code an RPG IV program, I have a template in the H-spec that runs about three pages. Really long, huh? Sure it is. But it's useful. That three-page H-spec contains all that anyone needs to know about the program: program purpose, indicator usage, data structure usage, file usage, procedure/function/module usage, any special notes (that are also in the code where they occur), and a modification table. Now, wouldn't a self-commenting program handle this for me? As Ed McMahon would say, "You are correct, sir!" There's a fine line between clarity of code and aiding other programmers. How often is an indicator's usage hard to determine? Granted, with V5Rx RPG IV, the free-form format now allows almost indicatorless coding. Still, there may be a few stragglers out there who use V4Rx or prior RPG and have to deal with them. Wouldn't it be nice to have one source to tell them what an indicator is used for? This may also help clarify to the programmer which indicators have been used so they are not reused for a different purpose. But, of course, that has never happened to any of us, has it? ;-)

A decent template should be a company standard. I call mine RPGSHELL. It is the first thing I copy in before I start to code, and it saves me a ton of questions! I have never had anyone ask me what an indicator was being used for or what an inadequately named data structure was used for. Most importantly, when I want to explain one of my programs to someone, I print out that oh-so-long multi-page H-spec, which just happens to be the front end to RPGSHELL. Life's great...when you have a concise template!

General notes are not the template notes I described above. These are the awkward notes that arise when programmers confuse comments with pseudo-code. An example would be describing the subsequent IF statement as "Set value of x to 0 if *IN76 is *ON; else set x to 7." Shouldn't self-commenting code do this for us? If you code around pseudo-coded comments, remove them afterward unless they are warnings. General notes should be few and far between--perhaps for the purposes of understanding why you're loading a table or pointer array or maybe to understand the ultimate purpose of a SELECT statement or a C++ Switch statement. While it is true that over-commenting is preferred to under-commenting, neither practice is good.

Cosmetics is that special categorization in which the issue is not really a comment but the statement that your program makes. Software programs out there will colorize comments, indent program statements on a printout, and perform nested loop matching by strategically placing notes somewhere (e.g., for RPG, usually prior to column 6 in the code). Admittedly, these are nice features that can aid the programmer in understanding the code. Just remember, they are cosmetic. They are fallible. Colorization is nice if everyone's system responds the same way. What if your red appears pink on someone else's screen? How do you set company standards for color to explain that to a new programmer? And what happens if someone decides they simply don't like a color and are given the authority to suddenly change it? How much standardization do we really need around comments? It shouldn't be so difficult.

Nested-loop matching programs scare me. I've seen it a million times: One programmer has made it a wonderful habit to use the nesting program each time a program modification is made to ensure those little buggers are kept up-to-date. Then, a new programmer comes in. A year later, one of the programmers two cubicles over yells out some language that can't be printed here. The now not-so-new programmer recollects that he didn't run the nest program. Nothing is wrong with the nest program. It can be run again. Still, a nightmare has been caused because an extra step wasn't done. Why is this so difficult? If you want to use nest programs, create a command that compiles your programs. Let the command processing program (CPP) invoke the nest program prior to compilation each time. The only company standard to create a program would be the compile command. Life is good again!

Cosmetics are a wonderful tool when used sparingly. They can aid in the analysis of a program and speed up program production and maintenance. On the other hand, cosmetics have a great potential for becoming a maintenance issue. Think about that.

My suggestions for how to handle nonessential comments are shown in Figure 3.

Figure 3: Nonessential Comment Do's and Don't's

So, what does it take to have a good commenting structure in your program? Start with a standard program template. Build your program as if it were a commentary on itself. You'll reduce the need for all the various notes and cautions and even tools if you follow those two suggestions. Add warnings only if they are absolutely necessary. Understand that self-commenting code is also highly understandable code, and fewer hassles will derive from well-written code. Self-commenting code is, by definition, less complicated. Most programmers use Advil because of analysis. Make it easier on others, and your own life will be less difficult. My complete list of commenting guidelines is in Figure 4.

Figure 4: Methodology for a Well-Commented Program

What do each of these steps do? They speak to all who touch the code. The programs speak to the programmers...a task that programs are charged with. And this is rightfully so.

One final note on comments: When it comes to commenting out old code...don't! Even though the comments may be in a different color, they tend to confuse more than assist future programmers. I recommend allowing your change management system to archive old code to resolve the issue. If you really feel old code may come back to haunt someone, code a comment stating that fact. You'll likely save yourself and your programmers a ton of trouble such as replacing old code with something new on a global find/replace!

Do your programs speak to other programmers? Do they even speak to you? If not, take a look at the methodology behind your comments. Determine if your program speaks without any comments. If your programs don't speak to you, then others can't listen either. Re-evaluate these programs. Refine them. It will improve your programs and reduce the number of times you sit down for a Q&A about them!

Vincent B. Goldsby has been an iSeries/400 programmer/analyst since its inception. Currently, he is a freelance speaker and instructor on ILE, RPG IV, and Introductory Java. His most requested course is a four-day comprehensive session entitled "Cameras, Lights, RPG IV!!!" He can be reached for comments and questions at This email address is being protected from spambots. You need JavaScript enabled to view it..