Use these techniques to ensure that you're writing effective and appropriate comments in your RPG code.

Written by Bryan Meyers and Jim Buck

Editor's note: This TechTip is an excerpt from the book Programming in RPG IV, 4th Edition.

Good programming style can serve a documentary purpose in helping others understand your source code. But use comments judiciously. If you practice good code construction techniques, you'll find that "less is more" when it comes to commenting the source. Too many comments are as bad as too few. Here are some specific commenting guidelines.

Use // Comments Exclusively

RPG IV now uses comments that begin with double slash characters (//) instead of the traditional asterisk (*) in position 7. In free-format code, which does not allow the asterisk format, the comment can begin anywhere in columns 8–80 and can even be on the same line with existing executable statements. The new comment form can also replace asterisk comments in fixed-format specifications, but the comment must be on a line all by itself. For the sake of consistency, use the new form exclusively, even in fixed-format specifications:

DName+++++++++++ETDsFrom+++To/L+++IDc.Functions+++++++++++++++++++++

// ------------------------------------------------------ Prototypes

D DayofWeek PR 1 0

D VarDate D

// ------------------------------------------------- Standalone variables

D DayNbr S 5 0

// ----------------------------------------------------------------------

// Main processing routine

// ----------------------------------------------------------------------

/Free

// Calculate total pay for employee

Chain(ne) EmployeeID Employees;

If %Found(Employees); // If employee active, calculate total pay

Eval(h) TotalPay = (RegHours * Rate) + (OvtHours * Rate * 1.5);

Endif;

/End-free

Use Comments to Clarify–Not Echo–Your Code

Comments that merely repeat the code add to a program's bulk but not to its value. In general, you should use comments for just three purposes:

• To provide a brief program or procedure summary
• To give a title to a subroutine, procedure, or other section of code
• To explain a technique that isn't readily apparent by reading the source

Always include a brief summary at the beginning of a program or procedure. This prologue should include the following information:

• The program or procedure title
• A brief description of the program's or procedure's purpose
• A chronology of changes that includes the date, programmer name, and purpose of each change
• A summary of indicator usage
• A description of the procedure interface (the return value and parameters)
• An example of how to call the procedure

Use "Marker Line" Comments to Organize Code

You can employ "marker line" comments to divide the major sections of your program. For example, you should definitely section off with lines of dashes (-) the declarations, the main procedure, each subroutine, and any subprocedures. Identify each section for easy reference:

DName+++++++++++ETDsFrom+++To/L+++IDc.Functions+++++++++++++++++++++++++

// ----------------------------------------------------------- Prototypes

D DayofWeek PR 1 0

D VarDate D

// ------------------------------------------------- Standalone variables

D DayNbr S 5 0

// ----------------------------------------------------------------------

// Main processing routine

// ----------------------------------------------------------------------

/Free

// Calculate total pay for employee

Chain(ne) EmployeeID Employees;

If %Found(Employees); // If employee active, calculate total pay

Eval(h) TotalPay = (RegHours * Rate) + (OvtHours * Rate * 1.5);

Endif;

/End-free

Use blank lines to group related source lines and make them stand out. In general, you should use completely blank lines instead of blank comment lines to group lines of code, unless you're building a block of comments. Use only one blank line, though; multiple consecutive blank lines make your program hard to read.

Avoid Right-Hand Comments

Right-hand "end line" comments in positions 81–100 tend simply to echo the code, can be lost during program maintenance, and can easily become "out of synch" with the line they comment. Especially now that comments can be inline with code, don't use right-hand comments.

Don't Use Positions 1–5

The original RPG IV syntax, which was oriented to using punched paper cards, used positions 1–5 to sequence program line numbers. In RPG IV, these columns are commentary only. You may use them to identify changed lines in a program or structured indentation levels, but be aware that these columns may be subject to the same hazards as right-hand comments.