04
Mon, Nov
6 New Articles

Legacy Maintenance: Evaluating and Documenting Business Rules in Legacy Code

General
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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.

 if (orderLine.getItem().isValid()
 && orderLine.getItem().hasAvailable(orderLine.getQuantity())
 orderLine.getItem().allocate(orderLine.getQuantity());

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.

http://www.mcpressonline.com/articles/images/2002/070725AD%20-%20Legacy%20Maintenance%20Evaluating%20and%20Documenting%20Business%20Rules%20in%20Legacy%20CodeV3--07250700.png

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:

http://www.mcpressonline.com/articles/images/2002/070725AD%20-%20Legacy%20Maintenance%20Evaluating%20and%20Documenting%20Business%20Rules%20in%20Legacy%20CodeV3--07250701.png

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:

http://www.mcpressonline.com/articles/images/2002/070725AD%20-%20Legacy%20Maintenance%20Evaluating%20and%20Documenting%20Business%20Rules%20in%20Legacy%20CodeV3--07250702.png

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.

http://www.mcpressonline.com/articles/images/2002/070725AD%20-%20Legacy%20Maintenance%20Evaluating%20and%20Documenting%20Business%20Rules%20in%20Legacy%20CodeV3--07250703.png

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.

http://www.mcpressonline.com/articles/images/2002/070725AD%20-%20Legacy%20Maintenance%20Evaluating%20and%20Documenting%20Business%20Rules%20in%20Legacy%20CodeV3--07250704.png

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.

http://www.mcpressonline.com/articles/images/2002/070725AD%20-%20Legacy%20Maintenance%20Evaluating%20and%20Documenting%20Business%20Rules%20in%20Legacy%20CodeV3--07250705.png

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

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 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 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 Eclipse: Step by Step
Quickly get up to speed and productivity using Eclipse.
List Price $59.00

Now On Sale

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

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: