Sat, Apr
5 New Articles

If a Program Never Speaks, Do You Listen?

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times
Before I became a programmer, I was a writer. Every writer is taught early on to communicate as effectively as possible. When I became a programmer, I discovered that program comments mimic writing quite well. A good comment gets right to the point without being verbose. However, it is better to have a verbose comment than no comment. As we go through the day-to-day duties of being programmers, we begin to forget this when we code.

How many times has old code become a maintenance nightmare because the program a) has no comments, b) has confusing comments, or c) has commented-out old code? If my own experience is any indication, the answer is "quite often."

Developing a decent commenting style is not difficult! I'll review some of the common mistakes and the ways to repair or correct them.

Commenting style should be in the programmer's mind before the first line of code is written. Why? Because a programmer should understand how the particular programming language provides comment support. There should also be some understanding of company standards prior to coding. Armed with this knowledge, you'll have the foundation for good programs (and good comments)!

I divide comments into two categories: essential comments and nonessential comments. As the terms suggest, essential comments designate those comments that a program must have to survive. Nonessential comments are comments that a program can survive and even thrive without. With few exceptions, nonessential comments are unnecessary.

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.

Use meaningful labels, tags, and variable names to clarify purpose (i.e., use TaxCalc instead of TxClc).
Opt for complex code when simple code is efficient and easy to interpret.
Avoid GOTOs where possible. Besides being bad programming practice, a GOTO can totally destroy the original purpose of a well-meaning tag.
Overdo use of tags and labels; too many just intrude on deciphering the program.

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.

Provide recovery information in unavoidable circumstances (i.e., "Check data structure xxx for last program status in the event of program crash").
Refer to specific program statement numbers; very difficult to maintain.
Warn of special environment needs, such as programs needing to be run in batch rather than as an interactive submit. Always explain why as well.
Use "time bombs" (i.e., date-, time- or version-sensitive messages); nearly impossible to maintain.

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.

Simplify the programmer's life when using corporate analysis tools; create alternate commands as company standards that themselves invoke the tools for indenting, colorizing, etc.
Increase the learning curve or the likelihood of human error by adding steps to the programming process.
Create a standard programmer template for defining the important elements of the program.
Restrict templates too much. Allow the programmer some area of expression in the programs.

Leave pseudo-code or other orphaned comments hanging in the program.

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.

A Well-Commented Program...
  • Begins with company standards for templates, programs, and tools
  • Evolves from the original template or shell framework into pseudo-code
  • Transforms into a self-commenting, efficient engine of productivity
  • Is enhanced by necessary warning messages, but preferably will not require them because you've developed other processes during the analysis phase
  • Is clear of pseudo-code and hard-to-maintain code and comments
  • Avoids generic notes that self-commenting code already speaks to
  • Doesn't require cosmetics to speak to other programmers even if the tools can aid in program analysis

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..



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: