Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

Last change on this file since 9851 was 9406, checked in by bensch, 18 years ago

orxonox/trunk: merged the proxy back

merged with commandsvn merge -r9346:HEAD https://svn.orxonox.net/orxonox/branches/proxy .

no conflicts

File size: 5.1 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 code must be documented with doxygen-tags (see 1.2).
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 "project_headers"
94#include <many_external_headers>
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  public: /* functions */
105   SomeClass();
106   ~SomeClass();
107
108   int mightyFunction(const std::string& name, int value);
109
110  private: /* functions */
111   void recompileInternalState();
112
113  protected: /* variables */
114    std::string someOtherMember; //!< some member, that can be touched by derived classes.
115
116  private: /* variables */
117   int usefullVariable;    //!< Usefull because
118   int coolVariable;       //!< this variable is cool, because...
119
120
121};
122
123#endif /* _SOMECLASS_H */
124
125
126
1273.2.CC-Files
128------------
129CC-files must be named the same as the .h-files they belong to.
130
131someclass.cc
132------------
133
134/*
135   orxonox - the future of 3D-vertical-scrollers
136
137   Copyright (C) 2004 orx
138
139   This program is free software; you can redistribute it and/or modify
140   it under the terms of the GNU General Public License as published by
141   the Free Software Foundation; either version 2, or (at your option)
142   any later version.
143
144   ### File Specific:
145   main-programmer: The Name of the author
146   co-programmer: ...
147*/
148
149#include "someclass.h"
150
151
152/**
153 * @brief <a brief description>
154 * @todo I think you get it.
155 *
156 * <more description>
157 */
158SomeClass::SomeClass (void)
159{
160   //constructor-stuff
161}
162
163/**
164 * @brief <a brief description>
165 * @todo if something is not destructed it will be here
166 *
167 * <more description>
168*/
169~SomeClass::~SomeClass (void)
170{
171  //destroy all te allocated space of the Class
172}
173
174/**
175 * @brief <a brief description>
176 * @param name <what is this parameter for>
177 * @param valuse <what for...>
178 * @returns <what it returns>
179 *
180 *  <more description>
181 */
182int SomeClass::mightyFuncion (const std::string& name, int value)
183{
184  this->coolVariable = value;
185  // and so on.....
186}
187
188// ... i think you get it :)
Note: See TracBrowser for help on using the repository browser.