libextensions - CodeRules.txt - emx/gcc *** (C) 2000 Arnd Hanses

Interfaces must be usable for C++ programs, therefore we must comply to the most 
recent ANSI C standard. This is not a K&R project! Try to write modern and compact C, 
easily maintainable by those unfamiliar to your code. Avoid namespace pollution. 
Ease debugging. Use Posix-conforming interfaces.

Please try to observe namely the following coding rules:

1) Always specify functions explicitly as 'static' or 'extern', in order to easily
   discriminate exported library api's and internal helper functions by means 
   of its formal declaration in header and source files.
   Functions are better discernible as such by immediately following braces:

   	foo(bar); not: foo		(bar).

2) Type safety is paramount: Reduce side-effects and document this by most liberal use 
   of the 'const' qualifier within the code and in public interfaces. 
   Memory addresses to be passed use 'void*' type (cast internally to correct type), 
   sizes use 'size_t' and offsets use the 'off_t' type.

3) Limit the scope of variables to where they are actually used. Global and static
   variables must be initialized to 0 or NULL; constants must be qualified as such.

4) Non-standard extensions (i.e. which are not described by Posix, X/OPEN, SUS)
   to be exported by the library are underscored and must contain at least one 
   Capital letter, so that they can be easily identified as non-conforming library 
   extensions. Global non-standard symbols, provided only for access from inside the 
   library (private members), are prepended by their doubly underscored module name.

5) All symbols which are not described by the recent ANSI C standard should exist
   in an underscored variant that the library uses to call them internally. This is to
   assure redefinitions by application programmers remain possible. The exported 
   alias without underscore should be defined in the header as an 'extern __inline__'
   function, calling the underscored variant: That one will be optimized out. 

   It should also be defined as an 'extern' library function, so that the '-fnoinline' 
   flag will call the existing library version.

6) Headers and additional text files document the interface. Library modules 
   describe the actual implementation.

8) Sections with debug code are enclosed with '#ifdef _DEBUG' and '#endif'. Use the
   macros '_dPuts(const char *string)' and '_dPrintf(const char *format, void *arg)'
   for debugging output. They are defined in various headers.

9) Comments should follow ANSI C conventions, just for conformance with:
   'gcc -ansi -pedantic'.

	 "/* bla */", not C++: "// blu"