View Full Version : Legacy Maintenance: Evaluating and Documenting Business Rules in Legacy Code
07-25-2007, 05:49 AM
"double slashes won't work in fixed-format code" Since when? We have lots of fixed-format code with double slash comments. As long as the first slash is in position 7 or after, it works fine (a slash in position 6 means it's a compiler directive, which is why the limitation). As for people who don't like double slash comments, how do they comment free-format, since the trusty column 6 asterisk doesn't work in it?
07-25-2007, 07:27 AM
Youíve written a great article and one that Iíve thought much about myself through the years. Here are a couple of those thoughts: Documentation should read like a novel. I donít really mean that you need Stephen King to write it but that it should be clear and readable by almost anyone (i.e. free of three letter acronyms and business jargon) and it should relate the code inside the program to real events going on in the outside world. Not only should there be business rule documentation (and there is darn little of it in any form) but it should be further broken down into P&L business rules and security (or cost of doing business) rules because they are different in nature.
07-25-2007, 07:38 AM
Sorry about that! You're right. Slashes don't work in RPG III, nor do blank lines, but both do work in fixed-format RPG IV! I should have been more specific, since I used slashes all the time in RPG IV before I went to free form. I guess that since I rarely code fixed-format RPG IV anymore, I didn't even think about it. Thanks for the clarification! As to the issue of double slashes, that's one of the reasons (excuses?) people use to justify not going to free form. They also don't like the semicolons, or the ugliness of embedded SQL (although that has been fixed). Joe
07-25-2007, 08:21 AM
My viewpoint may be skewed by my old age <grin>. When I started out in this business back in the days of cave computers, we used the waterfall development methodology. While there were many variants, the basic idea was you had a system requirements document, followed by a business analyst design, followed by a technical design, all of which was done prior to writing code. The business analysis was the place where screens got laid out and business rules were defined. So in a way, those documents served as our business rule documentation. But even that was incomplete, since additions, modification and bug fixes inevitably changed the actual processing of the business rules. Since so many of those steps are pretty much ignored these days (including the unit testing, system testuing and QA steps), the only place you're going to find the actual workings of the program are in the program source code itself, so I think it's even more important today that you include the types of comments I mention. In fact, it wouldn't hurt the industry to start to come up with some serious standards for program source documentation. Java has some of that in its Javadoc, but a lot of that is for the programmer by the programmer and really doesn't convey the business rules being implemented. We need a syntax specifically designed to specify rules. Joe
07-25-2007, 07:44 PM
Speaking as someone who probably pre-dates you in this industry Joe, I wholeheartedly agree with your sentiments. I firmly believe in documentation within programs, code review, and testing (perhaps I should add "the tooth fairly" to the list <grin>). However, I also have bitter experience of the problems caused by thorough but inaccurate documentation. I once ended up wasting several days because I believed the comments in an S/34 compiler source. When dealing with RPG or COBOL I would never have made that mistake - but if you have ever tried to debug on an S/34 an assembler program that was doing on the fly code patching you'll understand why I was tempted to believe the comments! So - when it comes down to it - the code is the arbiter - it is what is happening - and there will always be the chance that even the best of documentation will be wrong.
07-26-2007, 04:28 AM
Jon said: There will always be the chance that the best of documentation will be wrong.  So what are you suggesting? No documentation? Sure, the documentation may be defective, but so may the code be. It's up to the shop to enforce proper documentation standards just as they would enforce proper programming techniques. At the same time, I understand the possibility of being misled by the comments; it's up to anybody working on the code to take the comments with a grain of salt. Moreover in this particular case, I'm specifically talking about business rules documentation here, which is intended to identify the "why" more than the "how". That's why I'm careful to point out that good documentation doesn't simply echo the program; it explains the thought process behind the code. Joe
07-26-2007, 06:20 AM
I like Joe's next to last example best. IMO, the closer one can keep a statement's comment to the statement itself, the better its chances are for being accurate. We've all seen source where there's a big blob of comments followed by a big blob of statements. I've rarely come across accurate comments in that situation. My most hated are those that are placed at the top of a program that explain what this and indicator does, followed by a lists of files used, etc. Then, after coding all these comments, the author feels it unnecessary to comment a single line of code that follows. After the thing goes through a few significant mods, you might as well delete the whole block. In only one shop where I've worked were there commenting standards. What I learned there I use to this day---it's a habit, and although now I could get by with NO comments, I would never do it. It would make feel like I was ripping off the company. BTW, to Joe and others, anytime you all could post some examples like this, especially how they pertain to 3-tier (or 4-tier) design, I for one would appreciate it. I have never worked with a group that pursued that mode of thinking to any degree (they be some pretty lazy programmers around you know), but the more I see of it, the more I like it and understand the power of it.
07-26-2007, 09:15 AM
Speaking of program documentation.... what about the preamble? I always state the program description, the function, the author, date written, modification history, the compile commands, a complete description of every single parm (input only, output only, in/out, what it is, is it optional, date format if a decimal or char date, etc), and so forth. Nothing drives me crazy like having to study the code to figure out what the program does and how to call the program (parms). Chris
07-30-2007, 07:52 PM
I'm progressing in my tendency to write it that way.. Subprocedure names that help identify the service program, module, and the source file member in which it resides, as well as its function. It's a lot to ask, and even abbreviated results are long-ish, and it's just an ideal right now, but that's my thoughts. In formation... --Alan
07-30-2007, 07:52 PM
** This thread discusses the Content article: Legacy Maintenance: Evaluating and Documenting Business Rules in Legacy Code (http://www.mcpressonline.com/index.php?option=com_content&view=article&id=681) **
Powered by vBulletin® Version 4.1.5 Copyright © 2013 vBulletin Solutions, Inc. All rights reserved.