trunk/gosa-core/CODING

   1 GOsa coding guidelines
   2 ======================
   3
   4 * Scope of style guidelines
   5
   6 In order to keep the code consistent, please use the following conventions.
   7 These conventions are no judgement call on your coding abilities, but more
   8 of a style and look call.
   9
  10
  11 * Indentation and line length
  12
  13 As a basic style rule, please use spaces instead of tabulators. This will
  14 remove problems when using "diff" and avoid unneeded commits when using
  15 "subversion".
  16
  17 For VI users, this can be achieved by the following settings:
  18
  19 8<----------------------------------------------------------------------------
  20 set expandtab
  21 set shiftwidth=4
  22 set softtabstop=4
  23 set tabstop=4
  24 8<----------------------------------------------------------------------------
  25
  26 The line length should not exceed 80 characters. There is one exception for
  27 i18n strings that must not be split for gettext.
  28
  29
  30 *  Performance and Readability
  31
  32 It is more important to be correct than to be fast.
  33 It is more important to be maintainable than to be fast.
  34 Fast code that is difficult to maintain is likely going to be looked down upon.
  35
  36
  37 * Comments
  38
  39 Avoid perl style comments using "#". Always use "//" for single line comments
  40 and /* */ blocks for multi line comments.
  41
  42 8<----------------------------------------------------------------------------
  43 /*
  44  * This is a long comment...
  45  * ... which should look like this.
  46  */
  47
  48 // Short comment
  49 8<----------------------------------------------------------------------------
  50
  51
  52 * Documentation
  53
  54 8<----------------------------------------------------------------------------
  55
  56 8<----------------------------------------------------------------------------
  57
  58 svn propset svn:keywords "Id" file
  59
  60
  61 * File format
  62
  63 UTF-8, LF - not CR LF
  64 svn propset svn:eol-style native file
  65
  66
  67 * White spaces
  68
  69 Use a space before an opening parenthesis when calling functions, or indexing, like this:
  70
  71 8<----------------------------------------------------------------------------
  72 # Methods
  73 foo ($parameter);
  74
  75 # Arrays
  76 $b = $value [0];
  77
  78 # Readability
  79 if ($b + 5 > foo (bar () + 4)){
  80 }
  81 8<----------------------------------------------------------------------------
  82
  83 Don't layout your code like this, always minimize spaces:
  84
  85 8<----------------------------------------------------------------------------
  86 var $most           = "something";
  87 8<----------------------------------------------------------------------------
  88
  89
  90 Always use spaces to seperate arguments after commata:
  91
  92 8<----------------------------------------------------------------------------
  93 function foo ($param1, $param2)
  94 8<----------------------------------------------------------------------------
  95
  96 Always use single spaces to split logical and mathematical operations:
  97
  98 8<----------------------------------------------------------------------------
  99 if ( $a > 6 && $b == 17 && (foo ($b) < 1) ){
 100 }
 101 8<----------------------------------------------------------------------------
 102
 103
 104 * Braces
 105
 106 If statements with or without else clauses are formatted like this:
 107
 108 8<----------------------------------------------------------------------------
 109 if ($value) {
 110     foo ();
 111     bar ();
 112 }
 113
 114 if ($value) {
 115     foo ();
 116 } else {
 117     bar ();
 118 }
 119 8<----------------------------------------------------------------------------
 120
 121 Switches are formatted like this:
 122
 123 8<----------------------------------------------------------------------------
 124 switch ($reason) {
 125     case 'fine':
 126         foo ();
 127         break;
 128
 129     case 'well':
 130         bar ();
 131         break;
 132 }
 133 8<----------------------------------------------------------------------------
 134
 135
 136 Always use use braces for single line blocks:
 137
 138 8<----------------------------------------------------------------------------
 139 if ($value) {
 140     foo ();
 141 }
 142 8<----------------------------------------------------------------------------
 143
 144 Function definitions, Classes and Methods have an opening brace on the next
 145 line:
 146
 147 8<----------------------------------------------------------------------------
 148 function bar ()
 149 {
 150     ...
 151 }
 152 8<----------------------------------------------------------------------------
 153
 154
 155 * Casing
 156
 157 Always use camel casing with lowercase characters in the beginning for multi-
 158 word identifiers:
 159
 160 8<----------------------------------------------------------------------------
 161 function checkForValidity (){
 162   $testSucceeded = false;
 163   ...
 164 }
 165 8<----------------------------------------------------------------------------
 166
 167
 168 * Naming
 169
 170 Non trivial variable names should speak for themselves from within the context.
 171
 172 8<----------------------------------------------------------------------------
 173 // Use
 174 $hour = 5;
 175 // instead of
 176 $g = 5;
 177 8<----------------------------------------------------------------------------
 178
 179 Find short function names that describe what the function does - in order to
 180 make the code read like a written sentence.
 181
 182 8<----------------------------------------------------------------------------
 183 if ( configReadable ("/etc/foo.conf") ){
 184 }
 185 8<----------------------------------------------------------------------------
 186
 187 Use uppercase for constants/defines and _ if possible:
 188
 189 8<----------------------------------------------------------------------------
 190 if ( $speedUp == TRUE ) {
 191   $wait = SHORT_WAIT;
 192 } else {
 193   $wait = LONG_WAIT;
 194 }
 195 8<----------------------------------------------------------------------------
 196
 197
 198 * PHP specific
 199
 200 Open and close tags:
 201
 202   <?php
 203   // Something here
 204   ?>
 205
 206
 207 HTML
 208
 209 Do not include HTML code inside of your PHP file. Use smarty templating if
 210 possible.
 211
 212
 213 Code inclusion
 214
 215 Use require_once instead of include.
 216