[3183] | 1 | CODING-STANDARTS FOR ORXONOX |
---|
| 2 | -==============--==---+++++- |
---|
| 3 | In this file it is described how a orxonox-developer should structure his code. |
---|
| 4 | Every developer has to read it and follow the rules, and orxonox will grow. |
---|
[1855] | 5 | |
---|
[3183] | 6 | Contents: |
---|
| 7 | --------- |
---|
[1855] | 8 | 1.Coding Conventions |
---|
| 9 | 2.How to format your Code |
---|
[3183] | 10 | 3.Example |
---|
[1855] | 11 | |
---|
| 12 | 1.Coding Conventions |
---|
[3183] | 13 | ==================== |
---|
[1855] | 14 | ==> If you are beginning a new code-file: copy the proto_class.{cc,h} |
---|
| 15 | ==> and work with these files. |
---|
| 16 | |
---|
[3183] | 17 | 1.1.What has to be there: |
---|
| 18 | ------------------------- |
---|
| 19 | a) in every code file, there must be a GNU copyright header. |
---|
[1855] | 20 | |
---|
[3183] | 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. |
---|
[1855] | 23 | |
---|
[9406] | 24 | c) Every element of the code must be documented with doxygen-tags (see 1.2). |
---|
[1855] | 25 | |
---|
[3183] | 26 | 1.2.Doxygen Tags: |
---|
| 27 | ----------------- |
---|
| 28 | Doxygen tags in general are comments inside a file, that look just a bit different. |
---|
| 29 | most of the time they extend the /* or // with a second star or a ! |
---|
| 30 | |
---|
[9406] | 31 | a) h-files: |
---|
[3183] | 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, |
---|
[9406] | 40 | so if some comments is excluded by a #ifdef, #endif |
---|
[3183] | 41 | doxygen will not parse it. And ther will be nothing in the docu. |
---|
| 42 | |
---|
| 43 | |
---|
[1855] | 44 | 2.How to format your Code |
---|
[3183] | 45 | ========================= |
---|
[1853] | 46 | We 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 | |
---|
[3183] | 71 | |
---|
| 72 | |
---|
| 73 | 3.Example |
---|
| 74 | ========= |
---|
| 75 | 3.1.Header |
---|
| 76 | ---------- |
---|
| 77 | A standard header has the same name as the Class it handles. |
---|
| 78 | |
---|
| 79 | someclass.h |
---|
| 80 | ----------- |
---|
| 81 | /*! |
---|
[9406] | 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 | */ |
---|
[3183] | 89 | |
---|
| 90 | #ifndef _SOMECLASS_H |
---|
| 91 | #define _SOMECLASS_H |
---|
| 92 | |
---|
[9406] | 93 | #include "project_headers" |
---|
| 94 | #include <many_external_headers> |
---|
[3183] | 95 | |
---|
| 96 | //! short description of the class |
---|
| 97 | /** |
---|
[9406] | 98 | * @todo what remains to be done here |
---|
| 99 | * |
---|
| 100 | * longer description |
---|
| 101 | */ |
---|
[3183] | 102 | class SomeClass |
---|
| 103 | { |
---|
[9406] | 104 | public: /* functions */ |
---|
| 105 | SomeClass(); |
---|
| 106 | ~SomeClass(); |
---|
[3183] | 107 | |
---|
[9406] | 108 | int mightyFunction(const std::string& name, int value); |
---|
[3183] | 109 | |
---|
[9406] | 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 | |
---|
[3183] | 121 | }; |
---|
| 122 | |
---|
| 123 | #endif /* _SOMECLASS_H */ |
---|
| 124 | |
---|
| 125 | |
---|
| 126 | |
---|
| 127 | 3.2.CC-Files |
---|
| 128 | ------------ |
---|
| 129 | CC-files must be named the same as the .h-files they belong to. |
---|
| 130 | |
---|
| 131 | someclass.cc |
---|
| 132 | ------------ |
---|
| 133 | |
---|
[9406] | 134 | /* |
---|
[3183] | 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: |
---|
[9406] | 145 | main-programmer: The Name of the author |
---|
[3183] | 146 | co-programmer: ... |
---|
| 147 | */ |
---|
| 148 | |
---|
| 149 | #include "someclass.h" |
---|
| 150 | |
---|
| 151 | |
---|
| 152 | /** |
---|
[9406] | 153 | * @brief <a brief description> |
---|
| 154 | * @todo I think you get it. |
---|
| 155 | * |
---|
| 156 | * <more description> |
---|
| 157 | */ |
---|
[3183] | 158 | SomeClass::SomeClass (void) |
---|
| 159 | { |
---|
| 160 | //constructor-stuff |
---|
| 161 | } |
---|
| 162 | |
---|
| 163 | /** |
---|
[9406] | 164 | * @brief <a brief description> |
---|
| 165 | * @todo if something is not destructed it will be here |
---|
| 166 | * |
---|
| 167 | * <more description> |
---|
[3183] | 168 | */ |
---|
| 169 | ~SomeClass::~SomeClass (void) |
---|
| 170 | { |
---|
| 171 | //destroy all te allocated space of the Class |
---|
| 172 | } |
---|
| 173 | |
---|
| 174 | /** |
---|
[9406] | 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 | */ |
---|
| 182 | int SomeClass::mightyFuncion (const std::string& name, int value) |
---|
[3183] | 183 | { |
---|
| 184 | this->coolVariable = value; |
---|
| 185 | // and so on..... |
---|
| 186 | } |
---|
| 187 | |
---|
[9406] | 188 | // ... i think you get it :) |
---|