-*- outline -*-

coding - style
==============

  This is the coding style used for the initial parts of the 3D simulator.
  PLEASE everyone contributing try to use it as well. Even in case you 
  don't like specific parts: changes in the style guide would mean either
  inconsistencies or cause lot of work for changing the already existing 
  code. 


* Tabs 

  Never use hard tabs in your source files (have your editor insert
  spaces instead of tabs). This guideline is especially important. The
  use of hard tab characters ends up causing problems because not
  every editor uses the same number of spaces per tab character (in
  fact, most editors allow you to configure how many spaces there are
  per tab character). If you open a file with hard tabs already in it,
  instead of modifying the code so that it is readable in your own
  editor because your tab stops are different, please remove the
  tabs. There are several utilities which will do this.
  See also http://www.jwz.org/doc/tabs-vs-spaces.html

* Indentation

  Only four-space line indentation should be used. 

* Placing Braces

  Opening and closing braces should be on the same level of
  indentation below the token opening the scope. Opening and closing
  braces appear on a separate line by themselves.

  Example: 
 
void 
ClassName::function()
{
    if (x)
    {
        while (y)
        {
            // ...
        }
    }
    else
    {
        switch (z)
        {
            case 1:
            {
                // ...
                break;
            }
            default:
            {
                // ...
                break;
            }
        }
    }
}

* Naming Conventions

  class         ClassName;    // not Class_Name 
  struct        StructName;   // like classes
  typedef int   TMyInt;       // start with a capital T, 
                              // followed by a capital letter
  union		UnionName;    

** Enums

  Enumeration types 'enum' are starting with 'E', followed by a type-name 
  starting with a capital letter.

  Enumeration elements start with 'e', followed by the
  name of the constant starting with a capital letter

  Example:
  enum EEnumName
  {
      eEnumElement1,
      eEnumElement2
  };

** Functions:

   void 
   ClassName::FunctionName()

   - Function name starting with capital letter (!)
   - optional: place the return type on a separate line 
   - no blanks between function name and parenthesis

** Variables:

*** Variables with local scope 

   Variables with local scope start with a small letter. New words
   within the variable start with capital letters.

   Example: myVariable

*** Globally defined variables and constants

   Global constants and variables start witg 'g', followed by the
   variable name starting with a capital letter. New words within the
   variable name start with capital letters.

*** Member variables

   Member variables start with 'm', followed by the variable name
   starting with a capital letter. New words within the variable name
   start with capital letters.

   Example: mMemberVariable

   Constant static member variables are the same as the
   non-static types. 

   Examples: mStaticConstMemberVariable


** Macros 

  Macro names consist of only capital letters. Multi word macros are
  separated by underscore '_'.

  Example: MY_MACRO

* Comments

  Please use comments suitable for doxygen to get a nice HTML
  documentation. Comments should be placed above the respective
  elements

  Example:

  /*! This is a comment 
      for more than one line
  */

  //! This is a comment for exactly one line

** Gotchas
  
    There are some standard comments for parts of the code ('gotchas'): 
    ':TODO:',':BUG:'. Gotchas are the first part of a comment.

    Example:

    //:BUG: There is a bug below someone has to remove

    /*:TODO: The stuff below
             needs some clean up
     */

* Files

- file names consist of only small letters
- .h is the suffix for c++ header files, .cpp is the suffix for c++ source 
  files
- max line length is 80 characters
- include copyright:

/* -*- mode: c++; c-basic-offset: 4; indent-tabs-mode: nil -*-
   
   this file is part of rcssserver3D
   Fri May 9 2003
   Copyright (C) 2002,2003 Koblenz University
   Copyright (C) 2004 RoboCup Soccer Server 3D Maintenance Group
   $Id: codingstyle.txt,v 1.7 2004/02/12 14:07:21 fruit Exp $

   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; version 2 of the License.
  
   This program 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 General Public License for more details.
 
   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/


** Header files

Header files are protected by include guards, and the autoconf config.h file
should be included:

#ifndef MY_HEADER_FILE_H
#define MY_HEADER_FILE_H

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

But this usually doesn't take namespaces into account, which means that 
sometimes header files from different libs can clash, so I've started using

#ifndef NAMESPACE_MY_HEADER_FILE_H
#define NAMESPACE_MY_HEADER_FILE_H

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

where namespaces are used (which should be most of the time).

** Class declaration style

class ClassName
{
public:
	// public types

protected:
	// protected types

private:
	// private types
	
public:
	// public functions

protected:
	// protected functions

private:
	// private functions

public:
	// public members

protected:
	// protected members

private:
	// private members
};

* Options for GNU indent to fix broken code

  These are the options for GNU indent to get your code looking
  pretty much OK. Since indent seems to be a little bit non-deterministic, 
  better don't use it for files that are looking almost perfect :). 

-nbad -bap -sob --dont-star-comments --no-comment-delimiters-on-blank-lines
-cp33 -d0 -nfc1 -nfca -bl -bli0 -cli4 -cbi0 -ss -npcs -nprs -saf -saw -sai -cs
-ip0 -di1 -nbc -psl -bls -i4 -nut -ci0 -di1 -lp -l80 -nbbo -hnl

