l4/pkg/dde/coding_style.txt

   1 Coding style guidelines for DDE
   2 ###############################
   3
   4 Header of each file
   5 ===================
   6
   7 ! /*
   8 !  * \brief   Short description of the file
   9 !  * \author  Original author
  10 !  * \date    Creation date
  11 !  *
  12 !  * Some more detailed description. This is optional.
  13 !  */
  14
  15
  16 Identifiers
  17 ===========
  18
  19 * First character of class names uppercase, any other characters lowercase
  20 * Function and variable names lower case
  21 * 'Multi_word_identifiers' via underline
  22 * 'CONSTANTS' upper case
  23 * Private and protected members of a class begin with an '_'-character
  24 * Accessor functions are named after their corresponding attributes:
  25
  26   ! /**
  27   !  * Request private member variable
  28   !  */
  29   ! int value() { return _value; }
  30   !
  31   ! /**
  32   !  * Set the private member variable
  33   !  */
  34   ! void value(int value) { _value = value; }
  35
  36
  37 Indentation
  38 ===========
  39
  40 * Use one tab per indentation step. *Do not mix tabs and spaces!*
  41 * Use no tabs except at the beginning of a line.
  42 * Use spaces for alignment
  43
  44 See [http://electroly.com/mt/archives/000002.html] for a more detailed
  45 description.
  46
  47 This way, everyone can set his preferred tabsize in his editor
  48 and the source code always looks good.
  49
  50
  51 Vertical whitespaces
  52 ====================
  53
  54 In header files:
  55
  56 * Leave two empty lines between classes.
  57 * Leave one empty line between member functions.
  58
  59 In implementation files:
  60
  61 * Leave two empty lines between functions.
  62
  63
  64 Braces
  65 ======
  66
  67 * Braces after classnames and functions are placed at a new line:
  68   ! class Foo
  69   ! {
  70   !   public:
  71   !
  72   !     void function(void)
  73   !     {
  74   !       ...
  75   !     }
  76   ! };
  77
  78   except for single-line functions.
  79
  80 * All other occurrences of open braces (for 'if', 'while', 'for' etc.) are at the end of a line:
  81
  82   ! if (flag) {
  83   !   ..
  84   ! } else {
  85   !   ..
  86   ! }
  87
  88 * Surprisingly, one-line functions should be written on one line.
  89   Typically, this applies for accessor functions.
  90   If slightly more space than one line is needed, indent as follows:
  91
  92   ! int heavy_computation(int a, int lot, int of, int args) {
  93   !   return a + lot + of + args; }
  94
  95
  96 Comments
  97 ========
  98
  99 Function header
 100 ~~~~~~~~~~~~~~~
 101
 102 Each public or protected (but no private) function in a header-file should be
 103 prepended by a header as follows:
 104
 105 ! /**
 106 !  * Short description
 107 !  *
 108 !  * \param   a   Meaning of parameter a
 109 !  * \param   b   and b
 110 !  * \returns     Meaning of return value
 111 !  *
 112 !  * More detailed information about the function. This is optional.
 113 !  */
 114
 115 In the implementation files, only private functions should feature such
 116 function headers.
 117
 118
 119 Single-line comments
 120 ~~~~~~~~~~~~~~~~~~~~
 121
 122 ! /* use this syntax for single line comments */
 123
 124 A single-line comment should be prepended by an empty line.
 125 Single-line comments should be short - no complete sentences. Use lower-case.
 126
 127 C++-style comments ('//') should only be used for temporarily commenting-out
 128 code.  Such commented-out garbage is easy to 'grep' and there are handy
 129 'vim'-macros available for creating and removing such comments.
 130
 131
 132 Variable descriptions
 133 ~~~~~~~~~~~~~~~~~~~~~
 134
 135 Use the same syntax as for single-line comments. Insert two or more
 136 spaces before your comment starts.
 137
 138 ! int size;   /* in kilobytes */
 139
 140
 141 Multi-line comments
 142 ~~~~~~~~~~~~~~~~~~~
 143
 144 Multi-line comments are more detailed descriptions in the form of
 145 sentences.
 146 A multi-line comment should be enclosed by empty lines.
 147
 148 ! /*
 149 !  * This is some tricky
 150 !  * algorithm that works
 151 !  * as follows:
 152 !  * ...
 153 !  */
 154
 155 The first and last line of a multi-line comment contain no words.
 156
 157
 158 Source-code blocks
 159 ~~~~~~~~~~~~~~~~~~
 160
 161 For structuring your source code, you can entitle the different
 162 parts of a file like this:
 163
 164 ! <- two empty lines
 165 !
 166 ! /********************
 167 !  ** Event handlers **
 168 !  ********************/
 169 ! <- one empty line
 170
 171 Note the two stars at the left and right. There are two of them to
 172 make the visible width of the border match its height (typically,
 173 characters are ca. twice as high as wide).
 174
 175 A source-code block header represents a headline for the following
 176 code. To couple this headline with the following code closer than
 177 with previous code, leave two empty lines above and one empty line
 178 below the source-code block header.
 179
 180
 181 Order of public, protected, and private blocks
 182 ==============================================
 183
 184 For consistency reasons, use the following class layout:
 185
 186 ! class Sandstein
 187 ! {
 188 !   private:
 189 !     ...
 190 !   protected:
 191 !     ...
 192 !   public:
 193 ! };
 194
 195 Typically, the private section contains member variables that are used
 196 by public accessor functions below. In this common case, we only reference
 197 symbols that are defined above as it is done when programming plain C.
 198
 199 Leave one empty line (or a line that contains only a brace) above and below
 200 a 'private', 'protected', or 'public' label. This also applies when the
 201 label is followed by a source-code block header.