A Matter of Style – Labels…
As much as possible I try to make it obvious from a variable label, what type of variable it is and wherever possible, what other variable or control block it is related to.
Constants
I start variable names for constants with a # sign, thus:
#NAME DC C'NAME'
If a variable starting with a # sign is on the receiving end of an instruction, it is wrong because I should not be modifying constants!
Equates
I start equated value names with an @ sign, thus:
@ONE EQU 1 @FLAG1 EQU X'80'
For equated symbols that define a length, I add the suffix ‘_LEN’ to the symbol name, thus:
FIELD1 DS CL8 @FIELD1_LEN EQU *-FIELD1
That way, it is obvious in the code that I am referring to an equated length value, for example:
LA R1,@FIELD1_LEN Get field length in R1
It it obvious that I intend to load the field length and not the field address into the register but having the _LEN suffix ensures that I get the length and do not accidentally code the field address instead.
Equate/Field relationship
I prefer to ‘tie’ equated values for a field to the field they relate to by using a naming convention that uses the field name as part of the equate symbol, thus:
FIELD1 DS C @FIELD1_YES EQU C'Y' @FIELD1_NO EQU C'N' @FIELD1_NOTSET EQU X'00'
Then in code I would write something like this:
CLI FIELD1,@FIELD1_YES BE DO_YES CLI FIELD1,@FIELD1_NO BE DO_NO B NOT_SET
Similar code would apply to setting the field value, only use equated symbols that are related to the target field. This convention ensures that you are only setting and testing for values actually defined for the field.
About the only exception to this rule that I use is the use of the following common equated symbols:
@YES EQU C'Y' @NO EQU C'N' @POSTED EQU X'40'
@YES and @NO should be obvious, @POSTED is to test an ECB posted bit flag,E.G:
TM ECB1,@POSTED Is ECB posted?
BO DONE
Field/DSECT relationship
When I am creating my own DSECTS I prefer to prefix the name of each field within the DSECT with the DSECT name and an underscore, thus:
SOMEBLOK DSECT SOMEBLOK_FIELD1 DS CL8 SOMEBLOK_FIELD2 DS F @SOMEBLOK_LEN EQU *-SOMEBLOK
Using this standard makes it easy when reading source code to determine who owns a field. There is no confusion. The length equate for the control block also follows my convention of adding _LEN to the end and prefixing the equate symbol with an @ sign to avoid ambiguity in the executable code.
The exception to the rule…
I do allow for one exception to this rule though and that is for a program’s working storage. Typically I prefix working storage fields with the prefix STG_ (short for ‘storage’) although you can use anything you want, to identify working storage fields, for example W_ etc. It is preferable to use the underscore as part of the name to avoid situations where a field name ‘might’ happen to start with whatever prefix you are using. For example if you use just W as your working storage field prefix, is WORKF1 a field in your working storage or somewhere else? Using this convention, STG_WORKF1 or W_WORKF1 are obviously part of the code’s working storage. And again, the convention ensures that you are using the field you intend and not a WORK1 field defined somewhere else that might allow the program to assemble but my then fail at execution time because the storage it refers to is not addressable or it is addressable but it’s the wrong field and messes up some other code (good luck finding that one!).
Summary
Whatever conventions you use, the aim is to make it less likely to introduce errors when developing the code and to make it much easier to read, and locate field owners several months later when someone else has to try to follow, understand and debug or modify your code.
