$Id$


                             Table of Content
             1. Introduction
             2. Names of Header Files
             3. Definitions of Types, Functions etc
             3.1. Prefixes
             3.2. Function Definitions
             3.3. Type Definitions
             3.4. Enum Elements
             3.5. Macro Definitions
             3.6. Callbacks
             4. Formal Style
             4.1. Indent Style
             4.2. Brackets
             4.3. Start of Files
             5. ChangeLog
             6. BUILD Version Number
             7. Versioning
             8. CVS Usage
             9. Documentation




1. Introduction
===============

This file contains some style guidelines which I would like to see respected
by all authors contributing code to this project.

Nobody will wrench off your head if your submission does not follow these
guidelines, but you should be aware that your code will most likely be
modified to comply to this document.

The goal of these guidelines is to keep the project files uniform and thus
making it easier to read them.

This document is subject to changes, and the project admin is open for
discussion and suggestions.

I know that many parts of this project do not fully comply to this
style guide but I am working on it.



2. Names of Header Files
========================

For every module there may optionally be these header files:
- MODULENAME.h   prototypes and type definitions to be exported
- MODULENAME_p.h prototypes and type definitions to be used by the module
                 only (these files are not installed)
- MODULENAME_l.h prototypes and type definitions to be used by the library
                 only (these files are not installed)

MODULENAME must be the name of the module (like error) in all-lowercase
letters (this is to avoid problems with file systems which do not support
case sensitive file names).



3. Definitions of Types, Functions etc
======================================

Every type, function, macro etc that is exported must be introduced by the
keyword "GWENHYWFAR_API".
This is needed for WIN32 platforms to inform the compiler about which
symbols are to be imported from this project.

Every function must have a prototype. 
For exported functions they should be in the modules header file, for
non-exported functions these should be in the "MODULENAME_p.h" or in the
"MODULENAME_l.h" file.

Example: GWENHYWFAR_API void GWEN_DB_Group_free(GWEN_DB_NODE *n);


3.1. Prefixes
-------------
Every function or type name has two prefixes:
- GWEN_
    This forms a namespace "GWEN" which prevents function name
    collisions
- a module name 
    This makes every function name unique within GWEN.
    The module name should be all-capitals if the name is shorter than three
    characters or is an abbreviation. 
    It should start with a capital otherwise.

Please note that even internal functions (i.e. those which are not to be used
outside the library) MUST have these prefixes.

Examples: GWEN_DB_Values_Count, GWEN_Error_GetType


3.2. Function Definitions
-------------------------
Function names consist of multiple words combined by underscores.
Every word after the prefixes starts with a capital.
If any word itself consists of multiple sub-words (like in GetType) then
every sub-word should start with a capital, too.
This improves the readability of the code.

There is one exceptions from this rule (for historical reasons):
Functions which are constructors, destructors or duplication functions (like
GWEN_Buffer_new, GWEN_Buffer_free, GWEN_Buffer_dup) need to have the last word
start with a lowercase letter.
These functions also should use the given words below:
- _new  for constructors
- _free for destructors
- _dup  for deep copy duplications

Example: GWEN_DB_Values_Count, GWEN_Error_GetCode, GWEN_Error_new


3.3. Type Definitions
---------------------
Types are written in all-capitals, like in GWEN_DB_NODE.

Do not export structs per se. It is important that the real structure of the
structs used within Gwen is hidden. Members of structs must be accessed using
getter and setter functions. 
This makes sure that applications always use pointers instead of creating 
objects directly. This also reduces the number of incompatible API changes 
(those changes make it necessary for every depending package to be recompiled
and thus should be avoided where possible).


3.4. Enum Elements
------------------
New enum elements should consist of multiple words which are concatenated 
(like in GWEN_LoggerLevelError).
Unfortunately the enum definitions inside the GWEN_DB module do not follow
this guideline in this regard. Since changing this would produce many problems
this rule only applies to new enum definitions.


3.5. Macro Definitions
----------------------

Macro names are written in all-capitals, like in GWEN_DB_FLAGS_DEFAULT.


3.6. Callbacks
--------------

Callbacks must be attributed using "GWENHYWFAR_CB" to make them work. Best 
known callbacks in Gwenhywfar are those of the GWEN_INHERIT framework.
The following example illustrates this:

      void GWENHYWFAR_CB MyType_FreeData(void *bp, void *p);

As you can see the return type is followed by the keyword GWENHYWFAR_CB which
expands on WIN32 platforms to "__stdcall". This makes it possible to use such
callbacks on WIN32, too.
BTW: In a Linux environment this macro is expanded to an empty string because
Linux doesn't need such an attribute.
However, using the macro GWENHYWFAR_CB make the source code protable.



4. Formal Style
===============

4.1. Indent Style
-----------------
The preferred style is GNU: two space indent.


4.2. Brackets
-------------
The preferred style here is to have the opening bracket at the very same
line as the keyword which introduces the block, like in:

  if (pos) {
    if (pos>=bf->bufferSize) {
      DBG_ERROR(0, "Position outside buffer");
      return -1;
    }
  }

The closing bracket is supposed to be alone in the next line following the
block (as seen above).


4.3. Start of Files
-------------------
Every source file (*.{c, cpp, h}) should have a header like this:

------------------------------------------------- X8 cut here
/***************************************************************************
 $RCSfile$
 -------------------
 cvs         : $Id$
 begin       : Tue Sep 09 2003
 copyright   : (C) 2003 by Martin Preuss
 email       : martin@libchipcard.de

 ***************************************************************************
 *                                                                         *
 *   This library is free software; you can redistribute it and/or         *
 *   modify it under the terms of the GNU Lesser General Public            *
 *   License as published by the Free Software Foundation; either          *
 *   version 2.1 of the License, or (at your option) any later version.    *
 *                                                                         *
 *   This library 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     *
 *   Lesser General Public License for more details.                       *
 *                                                                         *
 *   You should have received a copy of the GNU Lesser General Public      *
 *   License along with this library; if not, write to the Free Software   *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 *                                                                         *
 ***************************************************************************/

------------------------------------------------- X8 cut here

The copyright and email entry should of course be adapted ;-)

All files within this project are licensed under the GNU LGPL, and the header
of every file must reflect that (as is in the header above).



5. ChangeLog
============

Every change to the CVS version of this project should be accompanied by
a descriptive text in the file ChangeLog.

The format of such an entry should match that of the existing entries,
currently these are emacs-style and "my style" ;-)

However, the format does not really matter, as long as it contains the 
following information:
- date of change
- name of the author of the changes
- description of the change

If the change breaks compatiblity with the previously existing version of this
project then this should be marked.



6. BUILD Version Number
=======================

The file "configure.ac" contains a line which sets the BUILD version number
(GWENHYWFAR_VERSION_BUILD=xyz).
Please update this number after a change (and just before committing your
changes)..

This has to do with the latency of the CVS server: Public CVS lags some hours
behind developer CVS, because public access is served from the CVS backup.

The BUILD version number allows to identify the version if some user wants to
try the current CVS version of this project but only draws an older version
because of the latency.



7. Versioning
=============

Starting with version 1.0 the following versioning scheme is to be used:
- if there are changes to the API which do not make it necessary to change
  the SO_MAJOR version (no addition to the API etc) then only the patchlevel
  version is incremented
- if there are changes which require the SO_MAJOR version to be incremented
  then:
  - if the SO_AGE is also incremented (i.e. there are downward compatible
    additions to the API) the minor version number is incremented and the 
    patchlevel is reset to 0.
  - if the SO_AGE is reset to 0 (i.e. the new API is not compatible to the
    old one) the major version is incremented and the other version parts
    are reset to 0.

Starting with version 1.4.2 the version numbers of released packages always 
use three digits.

Examples:
- version 1.2.1 has the same SO_MAJOR as 1.2.2, so 1.2.2 can completely
  replace 1.2.1 and vice versa without any problems
- version 1.3.0 is downward compatible to 1.2
- version 1.4.0 as well
- version 2.0.0 is incompatible with 1.x



8. CVS Usage
============

Please make sure that a commit to CVS does not make the CVS repository
unusable, so before committing:
- check whether your local version compiles correctly
- check whether the library/executable created actually DOES work

This is necessary because the CVS version is actually used by testers and the 
developers. So rendering the CVS version unusable would be disastrous...



9. Documentation
================

Every exported function and type should be documented inside a header file.
This project uses doxygen for this purpose.

Well, not every function is documented right now, but I am working on 
that ;-)



Martin Preuss, Hamburg/Germany, Feb 27 2006