Hi Jan,
OK Jan, you asked for it. I can't say they’re interesting, but here’s some of the things I do to make a pgm more readable. They are by no means original thoughts and may sound nit-picky and trivial but I think, in aggregate, they make a pgm more readable and therefore more maintainable. It may be helpful for those starting out to think about the points made here and use what they think makes sense and modify and adapt or reject those that they don't.
Structure:
The most important thing to do to “structure” a pgm is to structure its logic. I ask “is this the simplest most straightforward way to solve this problem?” I try to envision the code through the eyes of the reader and ask “if this was the first time I saw this code would I know what it was doing?” I try to think in terms of “processing blocks” and code those blocks using performs. There is also a thread here called "control break construct" posted 4/05/01 by slade and ammended by Crox and others. It discusses 2 approaches to coding for control breaks. They can be used as a template for any control break situation.
I try to code the “logic” of the pgm in the 1st 2 or 3 screens of code. I think of a pgm as a “document”. The 1st 2 or 3 screens serve as the table of contents; the pgraphs as chapters; the pgraph comments serve as the lead pgraph that explains the intent of the chapter. If that isn’t enough, I improvise.
When I comment paragraphs I attempt to tell what was “intended” in business, not technical terms. I only comment code whose intent is not obvious. If an "IF" stmt or any other, for that matter, references field values that don't convey the intent of the stmt in business terms I'll comment it.
Naming stuff:
To get the “logic” of the pgm up front, I relegate most of the one time stuff (opens, init code, closes, term code) to the bottom of the pgm, e.g., I usually code the init pgraph as 8nnn-init, print as 6nnn-..., other I/O as 7nnn-..., utility pgraphs as 5nnn-... (this last one only sometimes). I also try to keep sub-pgraphs numbered as sub groups of the main pgraph, e.g.:
Code:
2000-...
performs 2100-...
performs 2200-...
....
2100-...
performs 2110-...
2110-...
.....
.....
2200-...
....
....
I read somewhere that pgraphs should only perform 1 function and if you have a problem naming a pgraph, you probably have it doing too much. Sounded like sage advice to me. When naming “objects” (i.e. anything) I try to use known abbreviations, e.g. acct, prod, amt, cnt, etc. I also found that using nbr for number and num for numeric helps avoid confusion. I try to avoid names like ws-acct-1 ws-acct-2 when ws-master-acct and ws-tran-acct really defines what thes fields are. The same goes for pgraph names. It’s not easy to assign names, but it‘s worth the effort. And I’ll NEVER use 2 fields with names like this: ws-master-acct, ws-mstr-acct. This leads me to another point: try to be consistent, don’t use -ACCOUNT in one context and -ACCT in another. I even look at the copybooks I’ll be using to see what form of the word they use. Sometimes that works, but the idea is to keep it consistent. If I redefine a field I call it field-red. If I redefine it and change it from pic 9 to pic x, I call one field-num, the other field-an or field-9 field-x.
I consider “WS-” passe with the advent of power editing software available today. But doI use it to identify file record fields that reside in WS. I use FDxx- to identify file section record fields. The only exception is report recs. For them I use RH1-..., RH2-..., etc., RD1-..., RD2-..., etc., RT1-..., RT2-..., etc. I generally prefix any Linkage Section data items with LK- or LS-.
Miscelaney:
I don't use periods (.) to end sentences. I've found that it reduces errors when copying code from one part of a pgm to the middle of a nested if, as an example.
I end pgraphs with the mandatory period on a separate line. It also serves to delineate the pgraphs.
The general form of my PIC clauses look like this:
Code:
PIC X(002).
The leading zeros align the digits allowing easier totaling when the bytes in a group need totaling.
Note that there are 2 spaces before the X. This again aids alignment when signed numerics are coded, e.g.
PIC X(002).
PIC S9(004)V99.
