Code headers

All printable files must start with a header comment block. This block must have a comment character in the first column (see Table ) except for C-language source code where it must be enclosed by the comment characters. The header block must contain the required entries given in Table . The label must start just after the comment character (for C-code in the first column within a comment). The label may be truncated as indicated by lower case characters. If an entry exceeds one line it may be continued on the next. Such lines must either be indented or repeat the section label. In program source code additional comment blocks are required after each routine or function declaration (see Section ).

 

Table: Section labels for documentation in text files.

Label	Usage	Remarks
+++++++++++	Start of comment block	Required
.COPYRIGHT	Copyright statement	Required, Header
.IDENTifier	File name of module	Required, Header
.MODULE	Type of module
.AUTHOR	Name of creator	Required, Header
.KEYWORDs	Subject keywords	Required
.LANGUAGE	Language of module	Required, Header
.PURPOSE	General purpose of module	Required
.COMMENTs	Comments	Optional
.VERSION	Version no., date, etc.	Required, Header
.RETURNS	Return values for functions	Required, Routine
.ENVIRONment	Special environment requirements	Required
------	End of comment block	Required

 

The general layout of the section can be seen in the example for a User Manual given below. The VERSION section must have the format indicated, namely: version no., date, short description and initials of person making the change. New VERSION sections must be added each time a modification is made. Old VERSION sections must be maintained so that the full history of the module is present.