codingrules

	JPEG SYSTEM CODING RULES		27-SEP-91

Since numerous people will be contributing code and bug fixes, it's important
to establish a common coding style.  The goal of using similar coding styles
is much more important than the details of just what that style is.

I suggest we follow the recommendations of "Recommended C Style and Coding
Standards" revision 6.1 (Cannon et al. as modified by Spencer, Keppel and
Brader).  I have placed a copy of this document in the jpeg FTP archive (see
jpeg/doc/cstyle.ms.tbl.Z, or cstyle.txt.Z for those without nroff/tbl).

Unless someone has a real strong objection, let's do block comments thusly:

/*
 *  Block comments in this style.
 */

and indent statements in K&R style, e.g.,

	if (test) {
	    then-part;
	} else {
	    else-part;
	}

I suggest that multi-word names be written in the style multi_word_name
rather than multiWordName, but I am open to argument on this.


I would like to use function prototypes everywhere, and rely on automatic
source code transformation to feed non-ANSI C compilers.  The best tool
I have so far found for this is 'ansi2knr.c', which is part of Ghostscript.
ansi2knr is not very bright, so it imposes a format requirement on function
declarations: the function name MUST BEGIN IN COLUMN 1.  Thus all functions
should be written in the following style:

static int *
function_name (int a, char *b)
{
    code...
}

ansi2knr won't help with method declarations (function pointers in structs).
I suggest we use a macro to declare method pointers, something like this:

#ifdef PROTO
#define METHOD(type,methodname,arglist)  type (*methodname) arglist
#else
#define METHOD(type,methodname,arglist)  type (*methodname) ()
#endif

which is used like this:

struct function_pointers {
	METHOD(void, init_entropy_encoder, (functptrs fptrs, jparms *jp));
	METHOD(void, term_entropy_encoder, (void));
};

Note the set of parentheses surrounding the parameter list.

A similar solution is used for external function declarations (see the PP
macro in jpegdata.h).

If the code is to work on non-ANSI compilers, you cannot rely on a prototype
declaration to coerce actual parameters into the right types.  Therefore, use
explicit casts on actual parameters whenever the actual parameter type is not
identical to the formal parameter.  Beware of implicit conversions to "int".

It seems there are some non-ANSI compilers in which the sizeof() operator
is defined to return int, while size_t is defined as long.  Needless to say,
this is brain-damaged.  Always use the SIZEOF() macro in place of sizeof(),
so that the result is guaranteed to be of type size_t.


We can expect that the JPEG compressor and decompressor will be incorporated
into larger programs.  Therefore, the following rules are important:

1. Avoid direct use of any file I/O, "malloc", error report printouts, etc;
pass these through the common routines provided.

2. Assume that the JPEG code may be invoked more than once per program run;
therefore, do not rely on static initialization of variables, and be careful
to release all allocated storage at the end of processing.

3. Minimize global namespace pollution.  Functions should be declared static
wherever possible.  (Note that our method-based calling conventions help this
a lot: in many modules only the method-selector function will ever need to be
called directly, so only that function need be externally visible.)  All
global function names should begin with "j", and should be unique in the first
six characters for portability reasons.
Don't use global variables at all; anything that must be used in another
module should be put into parameters (there'll be some large structs passed
around for this purpose).

4. Source file names should also begin with "j"; remember to keep them to
eight characters (plus ".c" or ".h", etc) to make life easy for MS-DOSers.
Do not put code for both compression and decompression into the same source
file.