You are currently on IBM Systems Media’s archival website. Click here to view our new website.

IBM i > DEVELOPER > GENERAL

Documentation Made Easier

The dreaded D-word -- documentation -- is none too popular in any IT environment. But IBM Systems Magazine, Business Systems edition Technical Editors Jon Paris and Susan Gantner share some tips and tools that can make this necessary evil a little easier for you.

The dreaded D-word -- documentation -- is none too popular in any IT environment. But <em>IBM Systems Magazine, Business Systems edition</em> Technical Editors Jon Paris and Susan Gantner share some tips and tools that can make this necessary evil a l

Yes, you read that correctly. We said the D-word! Now before you all rush off pretending you didn't hear, our intention is to make your life easier. We don't like doing documentation any more than most of you. We’ve all heard that it’s for wimps and “real programmers” don't do it. In fact, with the snail-like pace of Jon's typing, you can be sure that documentation is very low on his list of fun things to do! We’re serious about making documentation as painless as possible, so this article focuses on some personal approaches and tools we’ve used to simplify it.

This article addresses documentation in the very broadest sense of the word--everything from a program’s internal documentation, to the tools we use to build documentation for end users, to a new tool that has some interesting possibilities for communicating with end users or even fellow team members. Hopefully, it’ll be a jumping-off point for you.

Internal Program Documentation Comments: One of the things we like the most about the /Free form RPG introduced in V5R1 is the new commenting style that it allows. Why is that so important? Because it lets us simply differentiate between comments that apply to a block of code and those that apply only to the line of code in question. Until the advent of the // style of comment, there was (in our opinion) no good way to do this. The approach favored by most people has been to code them as shown below:

* This comment applies only to the next line
  C      CustNo       Chain     CustMast

******************************************************
*                                                    *
* Whereas this one describes the block of code that  *
* follows. Or maybe introduces a subprocedure, or ...*
*                                                    *
******************************************************

We don't know about you, but to us those rows of asterisks are just plain ugly--and hyphens aren’t any better. We tend to feel that to be easy to read, and therefore understood, the comment should be aesthetically pleasing. It should only be jarring if that’s the intent! Using the new style of commenting, we can do it this way instead:

Chain CustNo CustMast; // This comment applies only to the line
                     // and can be continued if needed

//
// Whereas this one describes the block of code that
// follows. Or maybe introduces a subprocedure, or ...
//

Now that regular comments look a little less garish, we can always revert to the old style if we really want to draw attention to something.

Naming: We've talked about this many times before, but another thing we should all be doing is using mixed-case names in our programs. Some follow the convention of using a lowercase letter to introduce variables and an uppercase letter to introduce a procedure or subroutine. So custName identifies a variable, and GetCustName identifies a procedure. Some shops follow the practice of using all uppercase names for file and record names and for the names of variables that are externally described. Frankly, we don't find that terribly useful--it’s just too RPG III. If you’re using a good editor, such as WebSphere Developer Studio Client (WDSC) or Rational Developer for i (RDi), you don't need that extra clue; the Outline view will show you exactly where it’s defined and tell you its size and where it’s used, too. The other problem with using the uppercase convention is that it’s far too easy for someone to slip back into old habits, particularly if the shop still maintains RPG/400 programs.

The important thing is to determine a naming standard and enforce it. By the way, some misguided soul may suggest to you that all uppercase names are “easier to read.” After suppressing your manic laughter, our suggestion is that you quietly go away and wait until the next time you need to send them an e-mail, a report or whatever--and then write it ALL IN UPPERCASE. When they complain about it being hard to read, smile benignly and nod your head in agreement. You’ll usually find they change their opinion shortly thereafter.

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.



Advertisement

Advertisement

2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

Are You Multilingual?

Rational enables development in multiplatform environments

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters