source: orxonox.OLD/branches/cleanup/CODING-STANDARDS @ 10755

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 code must be documented with doxygen-tags (see 1.2).

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 "project_headers"
#include <many_external_headers>

//! short description of the class
/**
 * @todo what remains to be done here
 *
 * longer description
 */
class SomeClass
{
  public: /* functions */
   SomeClass();
   ~SomeClass();

   int mightyFunction(const std::string& name, int value);

  private: /* functions */
   void recompileInternalState();

  protected: /* variables */
    std::string someOtherMember; //!< some member, that can be touched by derived classes.

  private: /* variables */
   int usefullVariable;    //!< Usefull because
   int coolVariable;       //!< this variable is cool, because...


};

#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 the author
   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 (const std::string& name, int value)
{
  this->coolVariable = value;
  // and so on.....
}

// ... i think you get it :)