source: orxonox.OLD/trunk/CODING-STANDARDS @ 5344

CODING-STANDARTS FOR ORXONOX
-==============--==---+++++-
In this file it is described how a orxonox-developer should structure his code.
Every developer has to read it and follow the rules, and orxonox will grow.

Contents:
---------
1.Coding Conventions
2.How to format your Code
3.Example

1.Coding Conventions
====================
==> If you are beginning a new code-file: copy the proto_class.{cc,h}
==> and work with these files.

1.1.What has to be there:
-------------------------
  a) in every code file, there must be a GNU copyright header.

  b) under the (c) header write your name as main-programmer, if
     you are just bugfixing or extending write it under co-programmer.

  c) Every element of the must be documented with doxygen-tags.

1.2.Doxygen Tags:
-----------------
Doxygen tags in general are comments inside a file, that look just a bit different.
most of the time they extend the /* or // with a second star or a !

  a) h-files: 
   1) every h-file you want to be documented you have to tag. (tag looks like /*! \file somefile */ )
   2) every class has to be Documented. ( //! what it does)
   3) special variables can be documented. ( //!< wow this member is cool because )

  b) cc-files:
   1) all the methods must be documented, and all their parameters and return value must be covered.

  c) look out for this: Doxygen parses preprocessor arguments,
     so if some comments is excluded by a #ifdef, #endif 
     doxygen will not parse it. And ther will be nothing in the docu.


2.How to format your Code
=========================
We use the GNU conding convention (which is also used in xemacs etc.):

-- Put a space after every comma.
-- Put a space before the parenthesis that begins a function call,
   macro call, function declaration or definition, or control
   statement (if, while, switch, for). (DO NOT do this for macro
   definitions; this is invalid preprocessor syntax.)
-- The brace that begins a control statement (if, while, for, switch,
   do) or a function definition should go on a line by itself.
-- In function definitions, put the return type and all other
   qualifiers on a line before the function name.  Thus, the function
   name is always at the beginning of a line.
-- Indentation level is two spaces.  (However, the first and following
   statements of a while/for/if/etc. block are indented four spaces
   from the while/for/if keyword.  The opening and closing braces are
   indented two spaces.)
-- Variable and function names should be all lowercase, with underscores
   separating words, except for a prefixing tag, which may be in
   uppercase.  Do not use the mixed-case convention (e.g.
   SetVariableToValue ()) and *especially* do not use Microsoft
   Hungarian notation (char **rgszRedundantTag).
-- preprocessor and enum constants should be all uppercase, and should
   be prefixed with a tag that groups related constants together.




3.Example
=========
3.1.Header
----------
A standard header has the same name as the Class it handles.

someclass.h
-----------
/*!
  \file someclass.h
  \brief Some short description of the someclass
  \todo maybe there remains something to do in this entire file

  Here comes a longer description
  this can also be longer than one line
*/

#ifndef _SOMECLASS_H
#define _SOMECLASS_H

#include <many_headers>
#include "stdincl.h"

//! short description of the class
/**
  \todo what remains to be done here

   longer description
*/
class SomeClass
{
  private:
   int usefull_variable;
   int cool_variable; //!< this variable is cool, because...

  protected:
    char* someOtherMember;

  public:
   SomeClass (void);
   ~SomeClass (void);
   
   int mightyFunction (char* name, int value);
//....
};

#endif /* _SOMECLASS_H */



3.2.CC-Files
------------
CC-files must be named the same as the .h-files they belong to.

someclass.cc
------------

/* 
   orxonox - the future of 3D-vertical-scrollers

   Copyright (C) 2004 orx

   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, or (at your option)
   any later version.

   ### File Specific:
   main-programmer: The Name of Myself
   co-programmer: ...
*/

#include "someclass.h"


/**
   \brief <a brief description>
   \todo I think you get it.

   <more description>
*/
SomeClass::SomeClass (void)
{
   //constructor-stuff
}

/**
   \brief <a brief description>
   \todo if something is not destructed it will be here

   <more description>
*/
~SomeClass::~SomeClass (void)
{
  //destroy all te allocated space of the Class
}

/**
   \brief <a brief description>
   \param name <what is this parameter for>
   \param valuse <what for...>
   \returns <what it returns>

   <more description>
*/
int SomeClass::mightyFuncion (char* name, int value)
{
  this->coolVariable = value;
  // and so on.....
}

// ...