			AtheOS CODING STYLE


I will here try to explain the coding style used in AtheOS. This
document should be followed by any code you plan to submit to any of
the core components of the OS. Such as the kernel, appserver and the
various API libraries that is part of the core distribution. Since
AtheOS have a very sharp distinction between the kernel and it's
device drivers I will not pay to much attention to how the drivers
look.  I like to look at device drivers more like application, they
are loaded when needed, but is not a direct part of the kernel. I
whould afcourse still appreciate if this document was followed for
device driver's aswell, since I might need to do some maintaince on
them, but I will not reject any device driver cause they look ugly (to me).


			NAMING RULES

All variable names and struct/class members should be build from one
or more type prefixes followed by a mixed-case descriptive name.  The
prefixes is a great help when reading other peoples code (and your own
a few moments after it is written). It also make it easier to search
for members and variables since they tends to be more unique.
Only exception for this rule is counter variables and other iterators
typically used in loops. F.eks. it is legal to write

	for ( int i = 0 ; i < 16 ; ++i ) {
		DoStuff();
	}

Type prefixes:
	n - Any integer type (char, short, int, long and long long)
	v - Floating point types (float, double, long double)
	s - Structures
	c - Classes
	e - Enums
	u - Unions
	h - Handles (Variables that is never dereferenced, like
	    file-descriptors, message-ports, etc etc)
	f - Function (Only used in conjunction with the "p" prefix to
	    build function pointers)

Qualifier prefixes:
	p - Pointer to.
	a - Array of.

And no rule without exceptions:
	z - Zero terminated string.

All variables should be prefixed with one of the type prefixes:
	int	    nSize;
	float	    vScale;
	struct stat sStat;
	Rect        cBoundary;

If the variable is a pointer or an array the type prefix should
be prefixed with a qualifier:
	int	     anSizes[256];
	float*	     pvScale;
	struct stat* psStat;
	Rect         acRectangles[16];

In addition to the type prefix(es) all class members should be
prefixed with "m_" to distinguish them from local variables in member
functions.  Structure members should normaly be prefixed with a
abrivation of the structure name. This is not 100% required but since
many structures have matching member names, and that structure members
often match other variable names it is much easier to search for a
structure member if it have a prefix. Global variables and module
variables should have a "g_" prefix. Global variables should (for
obvious reasons) be very rare. Especially in C++ where there often is
better solutions (like singleton classes).

Member functions should have mixed-case names, while global function
should have lower-case only names with words separated by underscores(_).

Defines, macros and enum items should have uppercase-only names with
words separated by underscores.



			INDENTATION AND TAB SIZES

Defining the TAB size is easy, it is 8. Close to all text viewers
printers and editors have a default TAB size of 8. Using anything else
is asking for trouble.  The indendtion size, on the other hand is a
bit more debatable. I like to use small indention sizes (4) to get as
much width as possible. I know a lot of people find it hard to
distinguish between different indentions level when the indention
level is to small. I will therefor allow other indent-sizes as long as
the TAB size is 8 and the source contain Emacs local-variable
defintions to set the indention size whenever it differ from 4.



				BRACKETS

Brackets normally cause the most violent coding-style wars. I mean
that it is wrong to carve in stone where the brackets should be
placed. I put the bracket at the a line by itself when starting a
function, and when a scope grows large (more than a few lines).  This
make is easy to spot where the scope start and ends. For small scopes
with only a few lines of code I normaly put the starting bracket last
on the line to waist less space. As long as the starting bracket is
eighter at the end of the statment starting the scope, or on a line 
by itself in level with the opening statment it is fine by me.

	if ( a == 2 ) {
		printf( "a is 2\n" );
	}

	if ( a != 2 )
	{
		printf( "a is not 2\n" );
		printf( "it might be 3\n" );
		if ( a != 3 ) {
			printf( "No, not 3 eighter\n" );
		}
	}


				SWITCH/CASE

Brackets should be at the same indention level as the "switch" statement.
Each "case" labels should be one indention level deeper than the "switch"
statement. The code for each case should be one indention level deeper
than the "case" label.

	switch( nAction )
	{
		case CRASH_AND_BURN:
			SetFire();
			Crash();
			break;
		default:
			printf( "Unknown command: %d\n", nAction );
			break
	}

				PARANTESIS
There should NOT be any spaces between a function name and the opening
parantesis for the function parameter. For other constructs like for/while,
switch/case, etc the rules are not so strict. I like to have a space there
but it is not required.

				COMMENTS
Keep in mind that the API documentation is generated with Doxygen. Try to
write comments so as much documentation as possible can be automatically
extracted.



NOTE: This document may not be compleete. If some areas is not covered
repport it as a bug, and try to follow the style used in exsisting
code until this document is updated.



Kurt Skauen.
