   Copyright (C) 1996 Aladdin Enterprises.  All rights reserved.
  
  This file is part of GNU Ghostscript.
  
  GNU Ghostscript is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY.  No author or distributor accepts responsibility to
  anyone for the consequences of using it or for whether it serves any
  particular purpose or works at all, unless he says so in writing.  Refer to
  the GNU General Public License for full details.
  
  Everyone is granted permission to copy, modify and redistribute GNU
  Ghostscript, but only under the conditions described in the GNU General
  Public License.  A copy of this license is supposed to have been given to
  you along with GNU Ghostscript so you can know your rights and
  responsibilities.  It should be in a file named COPYING.  Among other
  things, the copyright notice and this notice must be preserved on all
  copies.
  
  Aladdin Enterprises is not affiliated with the Free Software Foundation or
  the GNU Project.  GNU Ghostscript, as distributed by Aladdin Enterprises,
  does not depend on any other GNU software.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

This file, c-style.txt, describes Aladdin's C coding guidelines.

For an overview of Ghostscript and a list of the documentation files, see
README.

Generalities
============

All the rules below are meant to produce code that is easy to read.  If you
find a rule getting in your way or producing ugly-looking results once in a
while, it's OK to break it.

Indentation
-----------

Tab stops are set every 8 columns.

File layout
-----------

Every code file should start with comments containing a copyright notice,
the name of the file, and a half-to-one-line summary of what the file
contains.

C code
======

Indentation
-----------

Put the first indentation point at the first tab stop.  Then proceed as
follows:

	{ ... in-line compound statement ...
	}
	... construct requiring subordinate code ...
	  ... subordinate simple statement ...
	... construct requiring subordinate code ...
	  { ... subordinate code ...
	  }

Or you can do this if you prefer:

	{
	  ... in-line compound statement ...
	}
	... construct requiring subordinate code ...
	  ... subordinate simple statement ...
	... construct requiring subordinate code ...
	  {
	    ... subordinate code ...
	  }

But not this:

	if ... {
	  ... subordinate code ...
	} else {
	  ... subordinate code ...
	}

Spaces
------

Do put a space:
	- after every comma and semicolon, unless it ends a line;
	- around every binary operator, although you can omit the spaces
	around the innermost operator in a nested expression if you like;
	- on both sides of the the parentheses of an if, for, or while.

Don't put a space:
	- at the end of a line;
	- before a comma or semicolon;
	- after unary prefix operators;
	- before the parenthesis of a macro or procedure call.

Types
-----

Use 'private' instead of 'static' for constructs (procedures and variables)
declared at the outermost scope.  This allows making such constructs either
visible or invisible to profilers with a single changed #define.

Use const wherever possible and appropriate.

Avoid global variables (non-const data) like the plague.  Avoid global const
data, but don't knock yourself out over it.

If you find yourself wanting to use void *, try to find an alternative using
unions or (in the case of super- and subclasses) casts.

Use anonymous structures as little as possible.  Declare structure types
like this (the _t on the type name is preferable but not required):

	typedef struct xxx_yyy_s {
	  ... members ...
	} xxx_yyy_t;

Names
-----

Use fully spelled-out English words in names rather than contractions.  This
is most important for procedure and macro names, global variables and
constants, #defined and enum values, structure and other typedef names, and
structure member names, and for argument and variable names which have
uninformative types like int.  It's not very important for arguments or
local variables of distinctive types, or for local index or count variables.

Procedures, variables, and structures visible outside a single .c file
should generally have a prefix that indicates what subsystem they belong to
(in the case of Ghostscript, gs_ or gx_).  This rule isn't followed very
consistently.

Commenting
----------

The most important descriptive comments are

Other
-----

Format procedures as follows:

scope return_type
proc_name(type1 arg1, type2 arg2, type3 arg3, type4 verylongargument4,
  type5 argument5)
{	... body ...
}

Leave a blank line after the declarations of local variables in a procedure
or compound statement, unless there's only 1 variable and the scope is less
than 10 lines or so.

PostScript code
===============

Put indentation points every 3 spaces.

Format procedure definitions like this:

/procname		% <arg1> <arg2> procname <result1> <result2>
 { ...code...
 } bind def
