Every file containing C or Tcl code--whether it is a header file, a resource file, or a file that implements a host tool, a library of routines, or an application--must contain a standard file heading. The conventions in this section define the standard for the heading that must come at the beginning of every source file.

The file heading consists of the blocks described below. The blocks are separated by one or more empty lines (in Tcl, empty comment lines) and contain no empty lines within the block. This facilitates automated processing of the heading.

• Title:  The title consists of a one-line comment containing the tool, library, or applications name followed by a short description. The name must be the same as the file name. This line will become the title of automatically generated reference entries and indexes.

• Copyright:  The copyright consists of a single-line comment containing the appropriate copyright information.

• Modification History:  The modification history consists of a comment block: in C, a multi-line comment, and in Tcl a series of comment lines. Each entry in the modification history consists of the version number, date of modification, initials of the programmer who made the change, and a complete description of the change. If the modification fixes an SPR, then the modification history must include the SPR number.

The version number is a two-digit number and a letter (for example, 03c). The letter is incremented for internal changes, and the number is incremented for large changes, especially those that materially affect the module's external interface.

The following example shows a standard file heading from a C source file:

Example A-1:  Standard File Heading (C Version)

/* fooLib.c - foo subroutine library */ 
 
/* Copyright 1984-1995 Wind River Systems, Inc. */ 
 
/* 
modification history 
-------------------- 
02a,15sep92,nfs  added defines MAX_FOOS and MIN_FATS. 
01b,15feb86,dnw  added routines fooGet() and fooPut(); 
                 added check for invalid index in fooFind(). 
01a,10feb86,dnw  written. 
*/