quakeforge/doc/CodingStyle

QuakeForge Coding Style
~~~~~~~~~~~~~~~~~~~~~~~

You /WILL/ indent with hard tabs, or you will be harmed. :) You can
format for whatever tab spacing you like, but if you indent with spaces
you will be hurt and you will have deserved it. :)

For best results, and to keep other developers from saying things like
"what bastard formatted this?", you should use 4-space tabs, because
that's what id used and what most of us use. This is only a guideline,
though, not a requirement.

Each source file should have a standard comment, formatted as in the
example below.

When you create a new source file, make sure you put an RCS ID below the
opening comment. One of the things this lets us do is use the "ident"
tool (comes with RCS) to identify all of the source files compiled into
an executable. This is done by embedding [dollar sign]Id: [dollar sign]
into the file, and CVS will automagically add the version information to
the source file.

All source files MUST #include "config.h" if the symbol HAVE_CONFIG_H
is defined. Likewise, no source file may be compiled multiple times to
produce different object files -- one source, one object.

Atop each function you write, you should attach a /* */ comment heading,
containing the name and a short, DESCRIPTIVE summary of the function's
purpose. Indent both of these with one or more tabs. The function is to
immediately follow the heading, with no space between. When you move or
rename a function, or change what it does, change the heading to match.

The return type should be located on the line previous to the function's
name, and the function's name should begin with the very first character
of a line. This is to facilitate easy searches for a function using the
simple regular expression "^FuncName".

Functions that do not take a value should be explicitly declared to
accept void, not simply ().

On brace style: QuakeForge code uses "cuddled" braces, also called K&R
and the One True Brace Style (yes, it really is called that), so-called
because it is the brace style used by the creators of the C language.

Please use a prefix for new functions. The currently-defined prefixes
are described below:

Cross-target prefixes:
IN_	Input
JOY_	Joystick (called by IN_* functions)
R_	Rendering
S_	Sound
VID_	Low-level video

Target-specific prefixes:

CL_	Client
GL_	OpenGL rendering
QFGL_	OpenGL portability aids
SNDDMA_	DMA Sound (called from S_*)
SV_	Server
SW_	Software rendering
X11_	X11R6-specific window handling

An example:

/*
	filename.c

	Description of this file

	Copyright (C) 2002 Your Name <your@email.addr>

	This program is free software; you can redistribute it and/or
	modify it under the terms of the GNU General Public License
	as published by the Free Software Foundation; either version 2
	of the License, or (at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

	See the GNU General Public License for more details.

	You should have received a copy of the GNU General Public
	License along with this program; if not, write to:

		Free Software Foundation, Inc.
		59 Temple Place - Suite 330
		Boston, MA  02111-1307, USA
*/

static const char rcsid[] = 
        "$Id$";

#ifdef HAVE_CONFIG_H
# include "config.h"
#endif

/*
	SECTION_FunctionName

	Description
*/
returntype
SECTION_FunctionName (args)
{
	type	var;

	for (var = 0; var; var++) {	// do something silly
		:
		:
	}
}

For switch statements:

switch (expr) {
	case X:		// foo
		:
		:
		break;
	case Y:		// bar
		:
		:
		break;
	default:	// fallthrough
		whatever;
}