nixawk
commented
7 years ago File Prolog
A file prolog introduces the file to the reader. Every file must have a prolog. Figure 5 is an example of a prolog outline; field values are described below.
/********************************************************************
* FILE NAME: *
* *
* PURPOSE: *
* *
* FILE REFERENCES: *
* *
* Name I/O Description *
* ---- --- ----------- *
* *
* EXTERNAL VARIABLES: *
* Source: < > *
* *
* Name Type I/O Description *
* ---- ---- --- ----------- *
* *
* EXTERNAL REFERENCES: *
* *
* Name Description *
* ---- ----------- *
* *
* ABNORMAL TERMINATION CONDITIONS, ERROR AND WARNING MESSAGES: *
* *
* ASSUMPTIONS, CONSTRAINTS, RESTRICTIONS: *
* *
* NOTES: *
* *
* REQUIREMENTS/FUNCTIONAL SPECIFICATIONS REFERENCES: *
* *
* DEVELOPMENT HISTORY: *
* *
* Date Author Change Id Release Description Of Change *
* ---- ------ --------- ------- --------------------- *
* *
* ALGORITHM (PDL) *
* *
*******************************************************************/-
File Name—Specify the name of the file.
-
Purpose— Briefly state the purpose of the unit.
-
File References—Specify the name, I/O, and description of files used by functions within this file. If the file does not have file references, indicate so by entering “none.”
-
External Variables—Specify the source, name, type, I/O, and description of variables being used by the unit that do not come in through the calling sequence. If the unit does not have external variables, indicate so by entering “none.”
-
External References—Specify the exact name of each unit called or invoked by this unit, followed by a one-line description of the unit. If the unit does not have external references, indicate so by entering “none.”
-
Abnormal Termination Conditions, Error and Warning Messages— Describe the circumstances under which the unit terminates abnormally. List error messages that this unit issues and briefly explain what triggers each.
-
Assumptions, Constraints, Restrictions—Describe the assumptions that are important to the design and implementation of the unit (e.g., “It is assumed that all input data have been checked for validity.”) Include descriptions of constraints and restrictions imposed by the unit (e.g., “The unit must complete its execution within 75 microseconds.”) This section contains information that explains the characteristics and peculiarities of the unit.
-
Notes—Specify any additional information needed to understand the file’s data or functions.
-
Requirements/Functional Specifications References—Provide traceability between requirements and specifications and implementation.
-
Development History—Outline the file’s development history:
- Date, day, month, and year of the change
- Author, author of the current implementation or change to the unit
- Change Id, an identification number for the change; e.g., if the change is related to a numbered SPR, that number may be used to correlate the change to the SPR
- Release, current software release and build in abbreviated form
- Description of Change, brief narrative describing the change
-
Algorithm (PDL)—Describe the algorithm used in the program in PDL format. See Section 4.2 for a detailed discussion of algorithm/PDL.
The organization of information within a file is as important to the readability and maintainability of your programs as the organization of information among files. In this section, we will discuss how to organize file information consistently. Figure 4 provides an overview of how program file and module information should be organized.