The template is divided into sections terminated by a blank line. Each section has lines with the following prefixes:-
SYNX: The syntax to be used.
E.G.: An example of the syntax.
NOTE: Additional notes to help explain what is wanted.
--------------------------------------------------------------------- SYNX: SUBROUTINE <routine name>(<arg. list>) E.G.: SUBROUTINE MTCONS(CIDH,IDN,IREQ,LAB) NOTE: If function declare type e.g. INTEGER FUNCTION ITEST. SYNX: SYNX:* SNOMAN: <1 or 2 line summary of function> E.G.: E.G.:* SNOMAN: MT system: Request management of titles bank. E.G.:* User callable. NOTE: Just enough detail to give basic function. SYNX: SYNX:* Contact: <name, location> SYNX:* Verified: <version, name, location, date> SYNX:* Refereed: <version, name, location, date> E.G.:* E.G.:* Contact: N. West, Oxford. E.G.:* Verified: 1_02, N. West, Oxford, 12 Jul 1992. E.G.:* Refereed: 1_01, A. N. Other, Somewhere, 14 Sep 1992. NOTE: The contact (which must be a single name) is not NOTE: necessarily the author but only the contact NOTE: can submit the routine when assembling the next version. NOTE: The code is normally verified by the contact name, minor NOTE: updates may not require full verification. NOTE: The referee verifies the original version of the routine and NOTE: may be called on to verify changes if sufficiently large. SYNX: SYNX:* Parameters:- SYNX:* ========== SYNX: SYNX:* <1st. arg> <in|out|in/out> <description> SYNX:* <2nd. arg> <in|out|in/out> <description> SYNX:* ... ... ... E.G.: E.G.:* Parameters:- E.G.:* ========== E.G.: E.G.:* CIDH in Char*4 bank name. E.G.:* IDN in Bank number. E.G.:* IREQ in Requirement level:- E.G.:* = 1 optional E.G.:* = 2 compulsory (fatal error if E.G::* missing). E.G.:* LAB in/out User Link Access Block (8 words long) NOTE: List parameters in the order they appear indicating which are NOTE: input,output or both. SYNX: SYNX:* Common Block Access:- SYNX:* =================== SYNX: SYNX:* <common> <in|out|in/out> <variables>, Banks: <bank names> E.G.: E.G.:* Common Block Access:- E.G.:* =================== E.G.: E.G.:* /MT/ in LREF,Banks: Requested bank CIDH E.G.:* out *,Banks: Requested bank DB header. E.G.:* ... ... ... NOTE: COMMON block access that is a crucial part of the interface NOTE: should be recorded i.e. communication between this routine and NOTE: its caller. Where a COMMON block holds a ZEBRA memory the NOTE: names of variables and the names of banks should both appear NOTE: (see example above). If many variables are accessed then NOTE: the shorthand * is sufficient. NOTE: NOTE: No need to record:- NOTE: NOTE: 1) "Evironmental" variables e.g. IQPRNT - it is part of the NOTE: operating environment. NOTE: 2) Internal access i.e. comunications between this routine NOTE: and routines it calls. SYNX: SYNX:* Specification:- SYNX:* ============= SYNX: SYNX:* o <"black box" specification> E.G.: E.G.:* Specification:- E.G.:* ============= E.G.: E.G.:* o Register request in array MTBMTB giving fatal error if E.G.:* full or system not initialised. E.G.: E.G.:* o Locate current version of requested bank giving fatal E.G.:* full or if compulsory but missing. E.G.: E.G.: ... NOTE: The idea is that the sections: Parameter, Common Block Access NOTE: and Specification should between them should completely NOTE: define what routine does, but NOT how it does it. SYNX: SYNX:* Program Notes:- SYNX:* ============= SYNX: SYNX:* <supplement to comments in code> E.G.: E.G.:* Program Notes:- E.G.:* ============= E.G.: E.G.:* See MT.TXT file for documentation about the MT system. E.G.: NOTE: This is the place to reveal any obscure features and sneaky NOTE: tricks used to make writing code more fun! Note: any NOTE: assumptions about the program state on entry to the routine NOTE: should appear in Specification. SYNX: SYNX:* Revision History:- SYNX:* ================ SYNX: SYNX:* <version> <author> <development> E.G.: E.G.:* Revision History:- E.G.:* ================ E.G.: E.G.:* 0.04 N. West First version. E.G.:* 0.05 N. West Bug fix. E.G.:* D. L. Wark Further bug fixes. E.G.:* M. D. Lay More bug fixes. NOTE: If multiple authors or modifications to a single version each NOTE: should appear on a separate line - see example. SYNX: IMPLICIT NONE E.G.: IMPLICIT NONE NOTE: IMPLICIT NONE is a RULE! SYNX: SYNX: INCLUDE <include file name in lower case> E.G.: INCLUDE 'mt.inc' E.G.: INCLUDE 'mteqv.inc' E.G.: INCLUDE 'zunit.inc' NOTE: The lower case keeps UNIX systems happy. SYNX: SYNX:* Argument Declarations:- SYNX:* ===================== SYNX: SYNX: <declaration of all arguments> E.G.: E.G.:* Argument Declarations:- E.G.:* ===================== E.G.: CHARACTER*4 CIDH E.G.: INTEGER IDN,IREQ,LAB(8) NOTE: By keeping argument declarations separate from local ones NOTE: means that the types of all arguments is easy to find and NOTE: need not be included in the Parameters section. SYNX:*ENDHEADER E.G.:*ENDHEADER NOTE: The *ENDHEADER marks the end introductory comments. The lines NOTE: between *FILE and *ENDHEADER can be used to provide a brief NOTE: routine write-up. SYNX: SYNX:* Local Variable Declarations:- SYNX:* =========================== SYNX: SYNX: <declaration of all local variables> E.G.: E.G.:* Local Variable Declarations:- E.G.:* =========================== E.G.: E.G.: INTEGER IDH, LBK, LBM,LBMMX, E.G.: + LLAB,LLBAC,LLABF, NWD, E.G.: + INTCHA, LOCF, IOR,IAND NOTE: This is the place to document the meanings of any variables NOTE: unless the comments in the code makes it clear. SYNX: SYNX: SAVE <list of variables> E.G.: E.G.: SAVE NOTE: Use this if required to ensure local variables are saved NOTE: between calls (but see section on Local Memories in the NOTE: Programmer's manual) SYNX: SYNX: <code> E.G.: ... NOTE: Try to keep code well structured into separate blocks each NOTE: introduced with blank and comment lines. SYNX: END E.G.: END NOTE: All good thing eventually come to this.