Function Definitions

This section concerns function definitions. Some of these conventions may be arbitrary, but are none the less useful for that. A typical example of a function definition looks like:

/*	Scan a line
**	-----------
**	This function scans a string for ...
**
** On entry,
**	l		points to the zero-terminated line to be scanned
** On exit,
**	*l		The line has null terminators inserted after each
**			 word found.
**	return value	is the number of words found, or -1 if error.
**	lines		This global value is incremented.
*/	
PRIVATE int scan_line (const char * line)
{
   /* Code here */
}

Separation of functions

White space of two lines separating functions

Name of the function

The identifier of the function right-justified to make it easy to find when flicking through a listing

Function header

The macros PUBLIC and PRIVATE (in HTUtils.h) expand to NULL and to static respectively. They show that one has thought about whether visibility is required outside the module, and they get over the overloading of the keyword "static" in C. Use one or the other. (Use for top level variables too).

Entry and exit conditions

It is most important to document the function as seen by the rest of the world (especially the caller). The most important aspects of the appearance of the function to the caller are the pre- and post-conditions. The preconditions include the value of the parameters and structures they point to. Both include any requirements on or changes to global data, the screen, disk files, etc.

We have a set of predefined exit values in HTUtils module.