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.