A plethora of products have been announced over the years that promise the ability to migrate your applications from one platform to an entirely different one. Some of them involve language-to-language migrating (RPG to Java is a popular one), while others move your applications into 4GL tools. I don't want to argue the efficacy of these tools; it would be up to the vendor to do that for you. I'll simply present my opinion that it's almost impossible to do this easily, at least with traditional monolithic programs.

However, what you can do is document your business rules. This will not only provide you with documentation for your current applications, but will also be your first step down the road toward modularizing your programs. Separating display logic from business logic is the first step toward the many benefits of service-oriented architecture (SOA).

What Is Documentation?

Before we venture too far down the road of documentation, though, we ought to define the term. True documentation is not an "echo" of the code, but is an explanation of it. That is, if a line says "MOVE CUSTNO XCUST," the comment should not be "move customer number." Now in the bad old RPG II and even RPG III days with confusing opcodes like MOVE (yes, I'm being mildly sarcastic here) and short, cryptic field names (but deadly serious here), such a comment might actually help a little bit because you might not realize that CUSTNO is customer number. It was even worse when you had a two-character prefix and non-normalized data; a field like PMAP07 might mean average price for period seven, or it might mean accumulated parts for 2007. So a short blurb telling you what the line was actually moving might help.

But that's not what I mean by documentation of business rules. In the perfect world, business rule documentation ought to be directly related to the original business requirements as dictated by the subject matter expert. Properly written, a non-programmer ought to be able to read the business rules documentation and be able to determine whether it's correct or not.

The "Self-Documenting Code" Issue

Whenever we talk about program documentation, the issue of self-documenting code comes up. The issue is a real one: Documentation is in effect double maintenance. No matter how well you document your code, whenever you change the business logic, you have to also change the documentation. Because if you don't, the result is not no documentation; the result is incorrect documentation, which is far worse. To that end, long names and functions and Boolean variables all help make the code more readable. However, even in languages that are designed to make that easier, I still think well-written English comments are required, especially in the business logic portion of the code.

This is not exactly what I consider to be readable, and this is a very simple example. The business rule in English is straightforward: "If the item is valid and has enough quantity available, then allocate the quantity ordered." In general, I think that the syntax of the programming language should focus on programming, leaving documentation to comments.

Business Logic vs. Application Control

Note that I mentioned the business logic portion of the code. That's because I consider that code to be separate from the rest of the application code. Programmers typically have a lot of leeway as to how they write their programs. Sure, there are often some corporate standards to adhere to and even code reviews in the stricter shops, but in general the programmer has a lot of leeway as to whether to use a FOR loop or a DO WHILE, or an EXSR versus a procedure call.

But when it comes to the business logic, the rules are external and come from the subject matter experts. And while the programmer has a bit of leeway as to the detailed mechanics of the code, the results must match specifically what the business analyst wanted. This can go even go so far as to specifying the actual order of edits and the messages that appear on failure.

Take a Look at a Typical Application

If I really wanted to make this difficult, I'd use an RPG III program, but I'll have mercy and use RPG IV. In fact, I'm going to use free-format RPG for the code in this example, since by now you should be at least considering free-format for your development. I realize that's something of a loaded statement, but we can take it up in another column.

The application is a standard monolithic maintenance program, with some display logic and some editing logic. I'd say this particular program is about halfway between the old-fashioned spaghetti code logic of yesteryear and a completely modular ILE type of approach. The code has been moved to free-form RPG IV but without the use of any internal procedures, thus allowing it to continue to run in the default activation group. It's not the prettiest code in the world, but I think it's a reasonable mix of old and new, such as might be found in any shop that is trying to balance between progressive coding and the bottom line.

Application Logic

Let me first take you to the application logic. Even though this section is purely programmer documentation (as opposed to business rule documentation), the concept of good comments vs. bad comments still applies. Let me show you the code.

Figure 1: This is the non-ILE template for a state-driven maintenance program. (Click images to enlarge.)

Even without any documentation, I hope you can see that there is an initialization step followed by a mainline loop (see, even RPG is self-documenting!). The program executes either subroutine Scr1 or Scr2, depending on which page of the data it is displaying, which is controlled by the field xwScr. The Scr1 function itself then uses a second state variable, xwFunc, to determine what to do on that screen. In this simple application, the program either displays the data to the user or processes the user's input. More complex screens might have a load subroutine as well, but that veers us off into application design, which is a different discussion entirely.

How Do We Comment?

So now it's time to comment a section of the code. This is where the idea of good and bad comments comes into play. You could have a bad comment:

Figure 2: This is a bad comment.

Yes, this is the bad end of the spectrum, but I bet you've seen comments of this nature. There might be a couple of extra comments peppered throughout here, such as "execute scr1," but it's still not particularly helpful. Let's now look at a more appropriate use of comments:

Figure 3: This is a much better comment block.

Here we have some comments that actually tell the reader what the program is doing. It documents the use of global state variables and also identifies boundary conditions (such as the invalid value for xwScr). One cool thing about this sort of commenting is that it can sometimes actually help you identify those boundary conditions that might otherwise go unchecked. For example, my first attempt at this design did not have the other clause, and one time I set the value to an invalid value. This caused a hard loop, which, as you might imagine, wasn't very pleasant. Commenting the code can help to show places where you are making assumptions.

Commenting Business Logic

As I noted earlier, the business logic for this particular application is already separated out of the program. In fact, there are a few very nice techniques already in use in this program, including a separate indicator area and named indicators for the display file. By itself, that helps to comment the code because it breaks out the business logic from the code. Again, this is an issue of architecture more than commenting, but I hope you can see that the design can actually help you in your coding.

Bad Comments

But that doesn't mean that the code can't still suffer from poor comments. Take a look at Figure 4.

Figure 4: Here's an entire routine whose comments add nothing to the code.

As you can see, each section of code has a single comment that really doesn't add to the understanding of the program. This is what I call "echoing." I actually read the term online, but the concept is simple: When your comments simply echo the code they are meant to comment, they don't provide any additional information. Instead, let's take a look at a couple of comments that do make the code more understandable.

Commenting for Readability

First, I want to show a snippet of code with two very different comment types in it.

Figure 5: The first two comment blocks are application comments, while the last block contains business rules comments.

This is an important bit of code. Now, please understand that this is simply one suggestion. If you don't like the specifics of how I do things, please don't let that detract from the overall message. For example, some people don't like the double slashes—and in fact, double slashes won't work in fixed-format code, so you'd have to use an asterisk. But that's not important to the point I'm trying to make.

Here's my point: Note that the first comment blocks in Figure 5 are very similar to the comment blocks in Figure 3. They're simply free-form descriptions of the code. I try to use complete sentences, although I do occasionally get terse, especially in the first line ("Clear errors"). But they do make clear what some of these global variables are and why I'm touching them (and where else they may get updated).

But note the last comment block. I have introduced a new concept of "typed" comments. That is, the first few characters of the comment actually identify the comment type. In this case, I have defined three categories of comments: BRD (Business Rule Definition), BRC (Business Rule Comment), and BRA (Business Rule Action). These are simply examples, and you can do this however you want, but the idea is straightforward:

As the name implies, a Business Rule Definition defines the business rule, hopefully in terms as close to the original business requirement as possible. A subject matter expert should be able to read this description and verify that it satisfies the requirement. A side benefit of the Business Rule Definition is that it should allow you to very easily define an error message. A Business Rule Comment contains additional comments about the business rule and may also further define some of the specific coding requirements for the rule. It acts as the bridge between the subject matter expert and the programmer (I'll show a more specific example in a moment). Finally, the Business Rule Action identifies the specific UI action that occurs when the rule is broken. I think it's important that there is a very specific statement of what the end user sees; this helps in creating a consistent user experience.

Figure 6: The business rule comments become much more powerful in complex rules.

In Figure 6, you see a more complex rule. It makes sure that the two unit-of-measure fields actually relate to one another by checking against a cross-reference file. Now, in the world of system design, there are two ways to maintain a conversion file such as this. First, whenever you write a record to the file with a from and to key and a conversion value, you also write a second record with the from and to reversed and the reciprocal conversion value. The other design is to simply write one record and make sure that the application programs check appropriately. This system does the latter, and the Business Rule Comment identifies that particular quirk in the system. That's a more realistic example of how the comment can help translate between the abstract concept and the concrete database definitions.

Side Benefits

You might not find this very appropriate for your shop. It would certainly be a lot of work to go back and retrofit this sort of commenting style to lots of existing programs. However, there are some serious side benefits that might not be immediately obvious.

First, if you do have a nice commenting style throughout your system, it's relatively easy to write a simple utility to go out to your source files and extract these comments. You could build a sort of automated reference of your system's business rules. This could be immensely helpful when trying to add new functionality or even debugging existing code.

A second, more subtle benefit comes when adding the comments themselves. As you add the comments to a block of code, any code that isn't directly related to the business rule sort of sticks out, because it doesn't fit into any of the business rules comments categories. If you can then rearrange the code to get that unrelated code out of the business logic, you are that much closer to completely encapsulating the business logic in your monolithic program. This is the Nirvana of business rule extraction that I alluded to at the very beginning of the article, which can ultimately lead to encapsulated business logic, SOA, and even migration.

And please, don't read into that statement that I'm advocating migration of mission-critical business systems. I would never do that. However, there may be business rules that might help you if they could be presented in another language or even on another platform, and the first step toward that capability is documenting what you have.

Joe Pluta is the founder and chief architect of Pluta Brothers Design, Inc. and has been extending the IBM midrange since the days of the IBM System/3. Joe uses WebSphere extensively, especially as the base for PSC/400, the only product that can move your legacy systems to the Web using simple green-screen commands. He has written several books, including E-Deployment: The Fastest Path to the Web, Eclipse: Step by Step, and WDSC: Step by Step. Joe performs onsite mentoring and speaks at user groups around the country. You can reach him at This email address is being protected from spambots. You need JavaScript enabled to view it..

Joe Pluta is the founder and chief architect of Pluta Brothers Design, Inc. He has been extending the IBM midrange since the days of the IBM System/3. Joe uses WebSphere extensively, especially as the base for PSC/400, the only product that can move your legacy systems to the Web using simple green-screen commands. He has written several books, including Developing Web 2.0 Applications with EGL for IBM i, E-Deployment: The Fastest Path to the Web, Eclipse: Step by Step, and WDSC: Step by Step. Joe performs onsite mentoring and speaks at user groups around the country. You can reach him at This email address is being protected from spambots. You need JavaScript enabled to view it..

---

MC Press books written by Joe Pluta available now on the MC Press Bookstore.

		Developing Web 2.0 Applications with EGL for IBM i Joe Pluta introduces you to EGL Rich UI and IBM’s Rational Developer for the IBM i platform. List Price $39.95 Now On Sale
		WDSC: Step by Step Discover incredibly powerful WDSC with this easy-to-understand yet thorough introduction. List Price $74.95 Now On Sale
		Eclipse: Step by Step Quickly get up to speed and productivity using Eclipse. List Price $59.00 Now On Sale

Also Read

The Power of Writing Code in a Low-Code Solution

TechTip: Let’s Have a Date, Part 2

Going off the Rails