Packages and File Structure

• Packages
• C Header Files
• C Source Files
• Structured Comments
  • CHeaderFile
  • CFile
  • Function
  • Macro
  • Struct and Variable
• Low-Level Coding Conventions

The names of C source files begin with the short package name followed by a series of English words (or abbreviations) with their first letters capitalized. No filename can be longer than fifteen characters. (This is a limitation imposed by the library archive program ar.)

Listed below are the names of files in an example package called rng. It has an external header file, an internal header file, a header file for portability, and two .c files. Other packages may have more .c files, but should not have more .h files.

Name	Contains
rng.h	Externally-visible functions, etc.
rngInt.h	Functions, etc., internal to the package
rngPort.h	#defines, etc., that hide system differences
rngUtil.c	Utility functions
rngIntUtil.c	Internal utility functions

C Header Files

1. A CHeaderFile structured comment describing the contents of the file. The external header file's comment should be directed toward programmers who will use the package; the internal header file's comment should be directed toward maintainers. Both should be self-contained.

2. #ifdef and #define statements that prevent this from being #included twice. In the external header file, the name should be an underscore followed by the short name of the package in all caps, e.g., _NTK. In the internal header file, the name should be an underscore followed by the short name of the package followed by ``INT'', e.g., _NTKINT.

3. In the internal header file, #include "vm.h", which will include the headers for all other packages. In the external header file, #include system header files only (i.e., those defined by ANSI C, e.g., #include <stdio.h>).

4. Declarations of non-functions, each type in a separate section with a leading comment.

5. An automatically-generated section surrounded by AutomaticStart and AutomaticEnd comments. Anything between these comments is removed by the automatic prototype extractor, so the programmer should put nothing here.

6. The #endif directive for the leading #ifdef.

/**CHeaderFile*****************************************************************

  FileName    [ required ]

  PackageName [ required ]

  Synopsis    [ required ]

  Description [ optional ]

  SeeAlso     [ optional ]

  Author      [ optional ]

  Copyright   [ required ]

  Revision    [ $Id: packages.html,v 1.2 1996/02/28 22:50:48 sedwards Exp $ ]

******************************************************************************/
#ifndef _
#define _

/*---------------------------------------------------------------------------*/
/* Constant declarations                                                     */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Type declarations                                                         */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Stucture declarations                                                     */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Variable declarations                                                     */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Macro declarations                                                        */
/*---------------------------------------------------------------------------*/

/**AutomaticStart*************************************************************/

/*---------------------------------------------------------------------------*/
/* Function prototypes                                                       */
/*---------------------------------------------------------------------------*/

/**AutomaticEnd***************************************************************/

#endif /* _ */

1. A CFile structured comment describing the contents of the file.

2. #include "packageInt.h".

3. An RCS string, used by the revision control system.

4. Declarations and definitions of non-functions, each type in a separate section with a leading comment.

5. An automatically-generated section surrounded by AutomaticStart and AutomaticEnd comments. Anything between these comments is removed by the automatic prototype extractor, so the programmer should put nothing here.

6. Three sections, each with a leading comment, separated into definitions for
   1. Functions visible outside the package
   2. Functions visible to all files within the package only
   3. Functions visible to the file only

/**CFile***********************************************************************

  FileName    [ required ]

  PackageName [ required ]

  Synopsis    [ required ]

  Description [ optional ]

  SeeAlso     [ optional ]

  Author      [ optional ]

  Copyright   [ required ]

******************************************************************************/

#include "Int.h"

static char rcsid[] = "$Id: packages.html,v 1.2 1996/02/28 22:50:48 sedwards Exp $";
USE(rcsid);

/*---------------------------------------------------------------------------*/
/* Stucture declarations                                                     */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Type declarations                                                         */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Variable declarations                                                     */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Macro declarations                                                        */
/*---------------------------------------------------------------------------*/

/**AutomaticStart*************************************************************/

/**AutomaticEnd***************************************************************/

/*---------------------------------------------------------------------------*/
/* Definition of exported functions                                          */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Definition of internal functions                                          */
/*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*/
/* Definition of static functions                                            */
/*---------------------------------------------------------------------------*/

Any definition (e.g., functions, macros, structures) must be preceded by a structured comment that indicates information about its functionality, use, etc. We suggest you write this documentation for your package before you write its code. This ensures the documentation gets written and allows you to see the package's complete interface.

A structured comment begins with a line beginning with ``/**'' (i.e., with no leading whitespace). The type of the comment (e.g., CFile, Function) is an alphanumeric string on the first line that may be embedded in asterisks or whitespace. A structured comment ends with a line containing ``*/''.

Between the start and end lines are field-value pairs separated by whitespace. A field is an alphanumeric string and a value is a square bracket-enclosed string that may include newlines. A value may not include a close-bracket unless it is escaped with a backslash, i.e., "5C]. The order of field-value pairs in a structured comment is irrelevant, but they must appear in pairs. A field-value pair named Comment is ignored by all automatic extraction tools, allowing comments within structured comments.

Certain values, such as the Synopsis and Description fields, may include HTML directives. These include <pre> and </pre>, which begin and end a section of preformatted text, i.e., that will be displayed with spaces and newlines intact, and <p>, which indicates a paragraph break.

CHeaderFile

FileName	required	The name of the header file
Package	required	The short name of the package, all lowercase
Synopsis	required	A one-line summary of the package
Description	optional	A more detailed description of the package, possibly multiple paragraphs. In the external header file, this should be directed toward users of the package. In the internal header file, this should be for maintainers of the package. This should be self-contained in both cases.
SeeAlso	optional	A space-separated list of names of things that may be of interest (e.g., packages, files, etc.)
Author	optional	The author or authors of the package
Copyright	required	A copyright notice for the file
Revision	required	The string $ Id: $, used by the revision control system.

An example CHeaderFile comment is shown below.

/**CHeaderFile***************************************************************
  FileName    [ rng.h ]
  PackageName [ rng ]
  Synopsis    [ Manipulation of integer ranges, e.g., 5-7. ]
  Description [ Routines for creating, adding to, querying, and
                deleting ranges. ]
  SeeAlso     [ rngInt.h ]
  Author      [ Gitanjali Swamy ]
  Copyright   [ Copyright (c) 1994-1996 The Regents of the Univ. of California.
                All rights reserved. ]
  Revision    [$Id: packages.html,v 1.2 1996/02/28 22:50:48 sedwards Exp $]
******************************************************************************/

FileName	required	The name of the source file
Package	required	The short name of the package, all lowercase
Synopsis	required	A one-line summary of the file's contents
Description	optional	A more detailed description of the file, possibly multiple paragraphs. It should be self-contained.
SeeAlso	optional	A space-separated list of names of things that may be of interest (e.g., packages, files, etc.)
Author	optional	The author or authors of the file
Copyright	required	A copyright notice for the file

An example CFile comment is shown below.

/**CFile*********************************************************************
  FileName    [ rngUtil.c ]
  PackageName [ rng ]
  Synopsis    [ Memory and read/write utilities for the Range package ]
  Description [ Contains routines for creating and deleting ranges,
                and asking questions of them ]
  SeeAlso     [ rngUtilInt.c ]
  Author      [ Gitanjali Swamy ]
  Copyright   [ Copyright (c) 1994-1996 The Regents of the Univ. of California.
                All rights reserved. ]
******************************************************************************/

Synopsis	required	A one-line synopsis of the function
Description	optional	A longer description of the function: its parameters, its return type, and how it is computed. This should be self-contained.
SideEffects	required	A description of any side effects (e.g., modification of global variables). If there are none, include an empty string: `` []}''.
SeeAlso	optional	A space-separated list of the names of related functions, files, packages, etc.
CommandName	optional	The name of the command that invokes this function. Omit when the function is not a command.
CommandSynopsis	optional	A one-sentence synopsis of the command.
CommandArguments	optional	The command-line arguments recognized or required by the command.
CommandDescription	optional	A full description of the command.

To document a function's parameters and return type, insert standard /* */-enclosed C comments after each parameter and after the return type. Parameter comments should follow the parameter name, before the comma or close-parenthesis. A return type comment should be between the return type and the function name. All of these comments are optional.

If the function can be invoked directly from the command line, it should include the Command fields. The sentence in the CommandSynopsis field should be an imperative command, e.g., ``read a network'' instead of ``reads a network.'' Omit a trailing period. The CommandArguments field should have symbolic names enclosed in angle brackets (e.g., <list>), and optional arguments enclosed in escaped square brackets (e.g., \[ -v \]). The CommandDescription field should fully document the command, and may use arbitrary HTML constructs.

An example Function comment with partial definition is shown below.

/**Function*******************************************************************
  Synopsis    [ Check if two ranges overlap ]
  Description [ If any integer is common to both of the given ranges,
                return TRUE, otherwise return FALSE. ]
  SideEffects []
  SeeAlso     [ Rng_RangeOrWithRange ]
******************************************************************************/
static boolean /* TRUE if the ranges overlap */
RangeOverlap(
  Rng_Range_t * range1 /* first range */,
  Rng_Range_t * range2 /* second range */)
{ /* ... */ }

To document the return type of a macro, insert a C comment with the type before the macro name. To document the type of each argument, insert a C comment before each argument. To document each argument, insert a C comment after each argument name, before a comma or close-parenthesis. All these comments are optional.

An example Macro comment with a partial definition is shown below.

/**Macro**********************************************************************
  Synopsis    [ Return the lower number in a range ]
  SideEffects []
  SeeAlso     [ Rng_RangeSetEnd ]
******************************************************************************/
#define /* int */ Rng_RangeReadEnd( /* Rng_Range_t * */ range /* the Range */)\
(((range->begin) =< RNG_MAX)? (range->begin): RNG_MAX)

Synopsis	required	A one-line synopsis
Description	optional	A longer description. This should be self-contained.
SeeAlso	optional	A space-separated list of the names of related functions, files, packages, etc.

To comment the fields in a structure definition, place a C comment after each field definition, after the semicolon. These comments are optional.

Example Struct and Variable comments are shown below.

/**Struct*************************************************************
  Synopsis      [ Represents an integer range ]
  Description   [ Uses two integers to represent the range.
                  Under normal circumstances, begin <= end. ]
  SeeAlso       [ Rng_RangeAlloc Rng_RangeFree ]
**********************************************************************/
typedef struct RngRangeStruct {
    int begin; /* The lower limit */
    int end;   /* The upper limit */
} Rng_Range_t;

/**Variable***********************************************************
  Synopsis      [ The number of ranges current in existence ]
  Description   [ Whenever Rng_RangeAlloc is called, this is incremented.
                  Whenever Rng_RangeFree is called, this is
                  decremented.  This should always be positive

  SeeAlso       [ Rng_RangeAlloc Rng_RangeFree ]
**********************************************************************/
int Rng_numRanges;

• Lines are eighty characters wide. Anything wider is difficult to read and print. Insert line breaks as necessary to ensure this.

• Indents are two spaces. This is smaller than other systems, but reduces the chance of nested instructions marching off the right side of the page.

• Comments within code occupy full lines. Comments tacked on to the right of statements can be hard to see and make it difficult to modify the code. Comments to the right of variable declarations, structure members, and arguments in function definitions are fine.

• Open-braces go at the end of lines. Close-braces should come at the beginning of a following line. The braces enclosing a function definition are the one exception to this rule.

  Always use curly braces in compound statements, even if they enclose only one statement. This makes it easier to correctly add statements to the block, and simplifies setting breakpoints in a debugger.

The following fragment illustrates these conventions.

void
Ntk_NodeDeclareAsCombinational(
  Ntk_Node_t * node,
  Tbl_Table_t * table,
  array_t * inputNames /* array of char */,
  int  outputIndex)
{

  /*
   * If the output column of a table can take only
   * a single value, set the constant flag. 
   */

  if ( Tbl_TableTestIsConstant(table, outputIndex) ) {
    node->constant = 1;
  }

  /*
   * Print the node's name, MDD id, type, and attributes.
   */

  (void)
    fprintf(fp, "%s: mdd=%d, %s;%s%s%s%s%s%s\n",
            Ntk_NodeReadName(node),
            Ntk_NodeReadMddId(node),
            typeString,
            (Ntk_NodeTestIsPrimaryOutput(node) ? " output" : ""),
            (Ntk_NodeTestIsConstant(node) ? " constant" : ""),
            (Ntk_NodeTestIsLatchDataInput(node) ?
             " data-input" : ""),
            (Ntk_NodeTestIsLatchInitialInput(node) ?
             " initial-input" : ""),             ,
            (Ntk_NodeTestIsCombInput(node) ? " comb-input" : ""),
            (Ntk_NodeTestIsCombOutput(node) ? " comb-output" : "")
            );
}