TechTip: Improving Free-Format Readability

[MCWebsite.Staff]

** This thread discusses the article: TechTip: Improving Free-Format Readability **
** This thread discusses the Content article: TechTip: Improving Free-Format Readability0

[johnny_dt99@yahoo.com]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
For new source code, you can use the LPEX editor in WDSc to create free-format RPG. Setting the automatic indent in preferences lets the editor do the work for you.

[Guest.Visitor]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
because it means someone must have written free-format code that needed it. If you're not going to indent -- don't use free format to begin with. Fixed format code is easier to read than non-indented free format code.

[Denny Davis]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
I had to increase the size of the RPG variable X from 3 to 7 digits. I also have have mod markings in columns 1 through 5 which it does not cope with.

[Guest.Visitor]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
Here's an updated version of the application that handles these. Thanks for the heads up. Mike[file name=6b261b8d_INDFREERPGv2.zip size=24]http://www.mcpressonline.com/images/fbfiles/files/6b261b8d_INDFREERPGv2.zip[/file]

[Guest.Visitor]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
Hi all, I was more than a little confused reading the title of this article; "Improving FREE format Readability". After all, many of us who cut our teeth on fixed-format languages later discovered how much easier it was to "read" free-format code "like C++" and even Basic. I remember Fortran 77 (which, granted made Assembler look archaic) and the similar fixed-format style that required you to have a spec-table card handy to decipher it-- much like all but those who have coded RPG II & III for most of their careers who have each position memorized. I was VERY scared that some set-in-his-ways guy had developed this utility to change perfectly readable and well-indented FREE code into fixed-format code-- Yikes!!!! While I understand that this is a subject of great debate (even with Cozzi), that IMHO would have been a step backwards. I was extremely relieved to see that not only was this NOT the case, but that Faust had even indented everything exactly as I teach my folks to do-- with readability and inherent logic heirarchy being of paramount importance. Anyhow, I agree that even having to write a program to clean-up FREE format code is disgusting. Proper indenting is even more important than proper commenting and both should be programming 101. That said, I'm glad that Faust took the time to create this utility. If reckless hacks keep coding FREE without proper indentation, it makes reverting back to fixed-format sound great! If I found myself having to write a similar utility in my shop, I would cut-to-the-chase and have a "Fire-and-Brimstone" speech with my developers

[H.Boldt]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
I agree - there should be no need for such a utility. Indenting code in a consistent manner should be second nature to all programmers. Of all code structuring techniques, proper indentation is right on the front line of code readability, and should be done properly right from the start when you type in new code. (Some languages actually enforce proper indentation!) But it's not the only technique for proper program structure. Mike's program illustrates the need for other structuring techniques. First, there's proper commenting. I'm not talking about one comment per line of code. That's generally too much. But a comment is generally necessary at least before each major block. Generally, before loops and non-trivial if statements, you need some explanation of what the block is trying to accomplish. (Technical explanation needed if something non-obvious is happening.) Oh yeah, whitespace between major blocks can also improve the readability of code. The next technique is modularization. That is, if you do something repeatedly in a program (like adding lines to the end of an array), that should be done in a separate procedure. That way, you can be sure that something is done the same way each time. Also, it helps to ensure your code isn't nested too deeply, which can impact program readability. Nesting more than 3-4 levels deep is a good sign that inner code should be in a separate procedure. This also helps if you have to move things from one nesting level to another. Another useful technique related to documentation is proper naming of variables. This can be a tricky issue, but if you ever see a statement like "If FreeOn = *Off;", many programmers will have to read it a couple of times to understand what it's really doing. (For an if statement like that, you might be better of coding "If FreeOn;", and reverse the then and else groups. Or choose a better name, like "WithinFreeGroup". Oh yeah, before I forget, note that compiler directives coded within /FREE blocks can begin anywhere between positions 7 and 80. I hope this program can take that into account. With that in mind, you also have to properly handle any line beginning with "/END-FREE". That particular stream of tokens can have two different meanings. In one context, it's a compiler directive. In another, it's part of an arithmetic expression where something on the previous line is divided by variable END with variable FREE subtracted from that. What's the difference? "/END-FREE" is to be interpreted as a compiler directive only if the previous statement ends with a semi-colon. (I'll leave it up to you to figure out when you're between statements versus in the middle of a statement.) (BTW, does anyone else remember seeing another indenting utility posted here a couple of years ago?) Cheers! Hans

[L.Marcus]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
While it may be true that programmers using Free format should be indenting their code anyway, a benefit to this utility is that it can be run on all Free format programs to standardize how they are indented and clean up anything that may have been overlooked. In a shop with multiple programmers, each having his/her own style, at least all the final code will conform to a single style.

[dlee@swbc.com]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
I personally think it sucks that we have free-format code in the first place. What are we trying to be java programmers? Fixed format did exactly what you are trying to accomplish, clean looking code. Why are we struggling so hard to get exactly where we are?

[R.Khoury]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
I agree as well. Isn't the whole point of free-format code to write RPG in a more readable, logical format? It's not the fact that it saves much typing ('cept for omitting Eval or Callp op-codes). Maybe the utility is a clean up utility for one that converted fixed-format to free format w/o indenting? Anyway - RPG Free is great - thanks to those who made it come to pass.

[eramirez@magmail.com]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
Program works slick, but I decided to run it against the cleanup program FDN001RG just for fun, and lo and behold it needed a little cleanup. This just goes to prove that even the best programmers with the best of intentions can always use a little help with indenting. Thanks for the program Mike.

[Guest.Visitor]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
It amazes me how all the neat features of modern RPG are things that COBOL programmers have used for decades.

[Guest.Visitor]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
DLee2319 wrote: > I personally think it sucks that we have free-format code in the > first place. What are we trying to be java programmers? Fixed format > did exactly what you are trying to accomplish, clean looking code. > > Why are we struggling so hard to get exactly where we are? I've never understood opinions like yours. I love free format and have been pushing all of the programmers I run into to begin using it. Free-format is elegant to code in and allows me to get work done more quickly. I also don't know where the Java opinions come from either, Free-format is much closer to Basic than to Java. Here's an example of why I love free-format: DoW cNextScreen <> 'End' ; Select ; When cNextScreen = 'Screen01' ; ExSr srScrn01 ; When cNextScreen = 'Screen02' ; ExSr srScrn02 ; Other ; cNextScreen = 'End'; EndSl ; Enddo ; Logic groups line up nicely, it's easy to bounce around in the Select group. If this were fixed format, I'd want to put a commented blank line between each When to make them stand out - but that isn't necessary with free. And I'll leave you with this: Dow Not (%EOF(Ninl03)) ; If inwhse = scrWhs ; // Check to see if this is a new combination or not. Select ; When scrType = 'IR' ; For x = 1 to %Elem(arrVarOrd) ; If arrOrd(x) = inref and arrVar(x) = %Subst(inemcc:8:8) ; Leave ; EndIf ; If arrOrd(x) = *Zeros and arrVar(x) = *Blanks ; bGotOne = *On ; arrOrd(x) = inref ; arrVar(x) = %Subst(inemcc:8:8) ; Leave ; EndIf ; EndFor ; When scrType = 'B' ; For x = 1 to %Elem(arrVarOrd) ; If arrOrd(x) = inref and arrVar(x) = inbomm ; Leave ; EndIf ; If arrOrd(x) = *Zeros and arrVar(x) = *Blank bGotOne = *On ; arrOrd(x) = inref ; arrVar(x) = inbomm ; Leave ; EndIf ; EndFor ; EndSl ; EndIf ; ReadE (scrType) Ninl03 ; EndDo ; Bill

[BT4]

TechTip: Improving Free-Format Readability

** This thread discusses the article: TechTip: Improving Free-Format Readability **
With the advent of the /free directive and named indicators, RPG finally can be coded in a manner almost consistent with English syntax. However, I am frustrated with IBM's definition of free-format. No such thing. Statements must begin past column 7 and cannot extend beyond column 80. When I bring up notepad for a quick and dirty HTML I can start coding in column 1 and if I were silly enough to do it, type tye whole document on 1 line. That is free-format. I can't understand why, in order to use a free format language like SQL within RPG, I have to exit free-format. Does anybody else see the irony of having to end free-format syntax in order to enter free-format SQL syntax? Why does an OPM construct, a subroutine fit into free-format and an ILE construct, subprocedure require me to exit free-format? (P,B E statements are not free-format.) Free-format still does not support a MOVE op code, or MOVEA, or CASxx. Fixed-format BITON/BITOFF operations are far easier to use than bitwise BIF's. But nice tool, good article. PS Indentation is good practice in RPG, or Java...

---

Code