Design Methodology › Step Four: Writing Process Code for the Dialogs › Writing the Dialog Specifications › Guidelines for Dialog Specifications

Guidelines for Dialog Specifications

The following guidelines are suggested when writing the specifications:

• Ensure that the specification narrative has all the information needed to write the program.
• Use the structure diagram and worksheets to obtain the proper dialog, record, and map names.
• Adhere to naming conventions.
• Use the data structure diagram and reports of the elements and records for details about the individual dialogs.
• Store the completed specification in the data dictionary, as comments in the premap process. Within process source, use the exclamation point (!) to lead all comments.
• If the specification is particularly long, store it as a separate module in the dictionary and copy it into the premap process code with an INCLUDE statement. In this way, the specifications are included in reports, but do not have to be viewed when the programmer is working on the source code.
• Refer to maps by name and location. As the design of the dialog maps would have been completed when building the prototype, it is unnecessary to duplicate the layouts in the specifications. If further definitions on map fields are required in order to write the code, these definitions should be included in the specifications and given to the data administrator.
• Incorporate other comments in the process source, as needed, especially at the beginning of response processes and subroutines. Batch programs and reports should also have their specifications included as comments within the code, unless the specifications are very long.

Some sites find it worthwhile to create a partitioned data set (PDS) or library for storing the specifications for each dialog. Such a data set can also be useful for central storage of the map templates and boilerplate code developed as programming aids.