==============================================================================
			 Programming Style Standards
		  Copyright (c) 1995 Q Studios Corporation
		    Contact: Peter Freese, CIS:74170,543
			   Last updated: 95/02/25
==============================================================================

This document provides standards for a uniform programming style to be used
in all Q Studios source code.  This document is NOT meant to be an absolute
set of rule to be followed -- it is a collection of recommendations based on
the need for code to be readable, maintainable, and less susceptible to
error.  The recommendations in this file apply specifically to C/C++.


COMMENTS

Each file should begin with a comment block of the following form:

/*****************************************************************************
    FILE:	    MISC.H

    DESCRIPTION:    This header file contains prototypes and inline
		    declarations for miscellaneous utility functions which
		    don't fall into any particular category or subsystem.

    AUTHOR:	    Peter M. Freese
    CREATED:	    95/02/01
    COPYRIGHT:	    Copyright (c) 1995 Q Studios Corporation
*****************************************************************************/

Each function should be prefaced by a comment block of the following form:

/*****************************************************************************
    FUNCTION:	    FindClosestColor()

    DESCRIPTION:    Finds the palette entry that most closely matches the
		    specified rgb value.

    PARAMETERS:     r, g, b are the DAC values to search for.

    RETURNS:        A palette index in the range 0 to 255.

    NOTES:          The global variable palette[] must already be
                    initialized.
*****************************************************************************/

Unused sections in the comment block may be omitted, e.g., void
functions do not need the RETURNS sections.  The NOTES section should
describe any function side effects or prerequisites.

Comments should be used liberally throughout source code.  C++ style //
comments are preferred for single line comments.  If multiple line comments
are necessary, then use C style /* */ comment blocks.  Avoid using visual
decoration such as '*' in the first column, since it makes text reformatting
difficult.

Comment blocks should be no wider than 80 characters.  I have created
MultiEdit macros for automatically building the various types of comment
blocks.


NAMING CONVENTIONS

Variable prefixes:

	a	Array
	b	Boolean
	c	Char
	g	Global
	i	Integer
	k	Constant
	l	Long
	p	Pointer
	s	String

Function names should use mixed case and should 'read' well.  This is best
accomplished by using a verb or verb and subject in the function name.
Examples of good function names are IsNumber(), ScrollScreen(), and
SpawnMissile().  Examples of bad function names are strncmpl(), neartag(),
and clockdir().

Aggragate types (structures, unions, and typedefs) should be declared in all
caps to distinguish them from variable and function names.

Functions which form a subsystem should all be prefaced by a 3 or 4 letter
lowercase abbreviation.  This classification provides an explicit scope
and association for the function name.  For example, it is obvious that
tioInit(), tioTerm(), and tioCursorOn() are all part of the same subsystem.


HEADER FILES

Every module should have it's own header file, and every exported variable,
function, or class should be prototyped in the header.

File wide variables and functions which are not explicitly exported
should be declared as static.

Header files should make use of exclusions to ensure that they are not
processed multiple times.  This is accomplished as follows:

#ifndef __FILENAME_H
#define __FILENAME_H

.
.	body of header file here
.

#endif


ASSERTIONS


FORMATTING


Everyone seems to have different ideas about what is best to use for tab
stops.  In my programming career, I have use 2, 3, 4, 5, and 8.  For C files,
I have settled on using tab stops of 4.  Four is a nice binary number, and it
conveys indenting clearly without overdoing it.  One argument against using
tab stops of 4 is that you can only indent half as many times as you can with
2 before running out of room.  I say you shouldn't be indenting that much
anyway.  If you need to nest conditionals 5 or 6 levels deep, you should
consider rewriting your function.

Opening and closing braces should align vertically, and should appear on
lines by themselves (with the exception of the do while construct.  The
whitespace provided by the braces lessons the density of information, and
makes for easier reading.  Blank lines should also be used to provided
visual separation between sub tasks.

Use 2 blank lines between the end of one function and the opening comment
block of another.

Here's a function example of coding style:

void InitControls( void )
{
    for (int i = 0; i < kMaxControls; i++)
    {
        char *p = iniGetKeyString("BLOOD.INI", "Keys", conInfo[i].iniKey, NULL);

	if ( p == NULL || *p == '\0' )
	{
	    control[i] = &keystatus[conInfo[i].default];
	}
	else
	{
	    long lScanId = strtoul(p, NULL, 16);
	    if ( lScanId == ULONG_MAX || lScanId > 255 )
	        lScanId = conInfo[i].default;

	    control[i] = &keystatus[lScanId];
	}
    }
}





