Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

Last change on this file since 3183 was 3183, checked in by bensch, 19 years ago

orxonox/trunk: new CODING-STANDARDS

File size: 4.8 KB
Line 
1CODING-STANDARTS FOR ORXONOX
2-==============--==---+++++-
3In this file it is described how a orxonox-developer should structure his code.
4Every developer has to read it and follow the rules, and orxonox will grow.
5
6Contents:
7---------
81.Coding Conventions
92.How to format your Code
103.Example
11
121.Coding Conventions
13====================
14==> If you are beginning a new code-file: copy the proto_class.{cc,h}
15==> and work with these files.
16
171.1.What has to be there:
18-------------------------
19  a) in every code file, there must be a GNU copyright header.
20
21  b) under the (c) header write your name as main-programmer, if
22     you are just bugfixing or extending write it under co-programmer.
23
24  c) Every element of the must be documented with doxygen-tags.
25
261.2.Doxygen Tags:
27-----------------
28Doxygen tags in general are comments inside a file, that look just a bit different.
29most of the time they extend the /* or // with a second star or a !
30
31  a) h-files:
32   1) every h-file you want to be documented you have to tag. (tag looks like /*! \file somefile */ )
33   2) every class has to be Documented. ( //! what it does)
34   3) special variables can be documented. ( //!< wow this member is cool because )
35
36  b) cc-files:
37   1) all the methods must be documented, and all their parameters and return value must be covered.
38
39  c) look out for this: Doxygen parses preprocessor arguments,
40     so if some comments is excluded by a #ifdef, #endif
41     doxygen will not parse it. And ther will be nothing in the docu.
42
43
442.How to format your Code
45=========================
46We use the GNU conding convention (which is also used in xemacs etc.):
47
48-- Put a space after every comma.
49-- Put a space before the parenthesis that begins a function call,
50   macro call, function declaration or definition, or control
51   statement (if, while, switch, for). (DO NOT do this for macro
52   definitions; this is invalid preprocessor syntax.)
53-- The brace that begins a control statement (if, while, for, switch,
54   do) or a function definition should go on a line by itself.
55-- In function definitions, put the return type and all other
56   qualifiers on a line before the function name.  Thus, the function
57   name is always at the beginning of a line.
58-- Indentation level is two spaces.  (However, the first and following
59   statements of a while/for/if/etc. block are indented four spaces
60   from the while/for/if keyword.  The opening and closing braces are
61   indented two spaces.)
62-- Variable and function names should be all lowercase, with underscores
63   separating words, except for a prefixing tag, which may be in
64   uppercase.  Do not use the mixed-case convention (e.g.
65   SetVariableToValue ()) and *especially* do not use Microsoft
66   Hungarian notation (char **rgszRedundantTag).
67-- preprocessor and enum constants should be all uppercase, and should
68   be prefixed with a tag that groups related constants together.
69
70
71
72
733.Example
74=========
753.1.Header
76----------
77A standard header has the same name as the Class it handles.
78
79someclass.h
80-----------
81/*!
82  \file someclass.h
83  \brief Some short description of the someclass
84  \todo maybe there remains something to do in this entire file
85
86  Here comes a longer description
87  this can also be longer than one line
88*/
89
90#ifndef _SOMECLASS_H
91#define _SOMECLASS_H
92
93#include <many_headers>
94#include "stdincl.h"
95
96//! short description of the class
97/**
98  \todo what remains to be done here
99
100   longer description
101*/
102class SomeClass
103{
104  private:
105   int usefull_variable;
106   int cool_variable; //!< this variable is cool, because...
107
108  protected:
109    char* someOtherMember;
110
111  public:
112   SomeClass (void);
113   ~SomeClass (void);
114   
115   int mightyFunction (char* name, int value);
116//....
117};
118
119#endif /* _SOMECLASS_H */
120
121
122
1233.2.CC-Files
124------------
125CC-files must be named the same as the .h-files they belong to.
126
127someclass.cc
128------------
129
130/*
131   orxonox - the future of 3D-vertical-scrollers
132
133   Copyright (C) 2004 orx
134
135   This program is free software; you can redistribute it and/or modify
136   it under the terms of the GNU General Public License as published by
137   the Free Software Foundation; either version 2, or (at your option)
138   any later version.
139
140   ### File Specific:
141   main-programmer: The Name of Myself
142   co-programmer: ...
143*/
144
145#include "someclass.h"
146
147
148/**
149   \brief <a brief description>
150   \todo I think you get it.
151
152   <more description>
153*/
154SomeClass::SomeClass (void)
155{
156   //constructor-stuff
157}
158
159/**
160   \brief <a brief description>
161   \todo if something is not destructed it will be here
162
163   <more description>
164*/
165~SomeClass::~SomeClass (void)
166{
167  //destroy all te allocated space of the Class
168}
169
170/**
171   \brief <a brief description>
172   \param name <what is this parameter for>
173   \param valuse <what for...>
174   \returns <what it returns>
175
176   <more description>
177*/
178int SomeClass::mightyFuncion (char* name, int value)
179{
180  this->coolVariable = value;
181  // and so on.....
182}
183
184// ...
Note: See TracBrowser for help on using the repository browser.