lang/de/docs/coding.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>Moodle Dokumentation: Coding Guidelines</title>
   5 <link rel="stylesheet" href="docstyles.css" type="TEXT/CSS">
   6   <script language="JavaScript" type="text/javascript">
   7   <!-- //hide
   8   var themeCSS = "<?php echo "$CFG->wwwroot/theme/$CFG->theme" ?>";
   9   if (themeCSS.indexOf("CFG->wwwroot") != true) {
  10     document.write ("<link rel=\"stylesheet\" type=\"text/css\" href=\"" + themeCSS +"/styles.php\" />");
  11     document.write ("<link rel=\"stylesheet\" type=\"text/css\" href=\"" + themeCSS +"/docstyles.php\" />");
  12   }
  13   // done hiding -->
  14   </script>
  15 <meta http-equiv="Content-Type" content=
  16 "text/html; charset=us-ascii">
  17 </head>
  18 <body bgcolor="#FFFFFF">
  19 <h1>Moodle Coding Guidelines</h1>
  20 <p class="normaltext">Die Stabilit&auml;t eines Programms wie
  21 Moodle h&auml;ngt weesentlich davon ab, dass alle Entwickler des
  22 Programmcodes bestimmte Grundregeln einheitlich anwenden. Diese
  23 sind hier definert.</p>
  24 <p class="normaltext">Dieser Text wird vorl&auml;ufig nicht ins
  25 Deutsche &uuml;bersetzt. Wir gehen davon aus, dass alle Anwender,
  26 die selber Programmteile f&uuml;r Moodle bearbeiten wollen so
  27 viel Englisch lesen und verstehen k&ouml;nnen dass sie diesen
  28 Text im Original verstehen.</p>
  29 <p class="normaltext">Any collaborative project needs consistency
  30 and stability to stay strong.</p>
  31 <p class="normaltext">These guidelines are to provide a goal for
  32 all Moodle code to strive to. It's true that some of the older
  33 existing code falls short in a few areas, but it will all be
  34 fixed eventually. All new code definitely must adhere to these
  35 standards as closely as possible.</p>
  36 <h2>General Rules</h2>
  37 <ol class="normaltext">
  38 <li class="spaced">All code files should use the .php
  39 extension.</li>
  40 <li class="spaced">All template files should use the .html
  41 extension.</li>
  42 <li class="spaced">All text files should use Unix-style text
  43 format (most text editors have this as an option).</li>
  44 <li class="spaced">All php tags must be 'full' tags like
  45 <font color="#339900">&lt;?php ?&gt;</font> ... not 'short' tags
  46 like <font color="#339900">&lt;? ?&gt;</font>.</li>
  47 <li class="spaced">All existing copyright notices must be
  48 retained. You can add your own if necessary.</li>
  49 <li class="spaced">Each file should include the main config.php
  50 file.</li>
  51 <li class="spaced">Each file should check that the user is
  52 authenticated correctly, using require_login() and isadmin(),
  53 isteacher(), iscreator() or isstudent().</li>
  54 <li class="spaced">All access to databases should use the
  55 functions in lib/datalib.php whenever possible - this allows
  56 compatibility across a wide range of databases. You should find
  57 that almost anything is possible using these functions. If you
  58 must write SQL code then make sure it is: cross-platform;
  59 restricted to specific functions within your code (usually a
  60 lib.php file); and clearly marked.</li>
  61 <li class="spaced">Don't create or use global variables except
  62 for the standard $CFG, $SESSION, $THEME and $USER.</li>
  63 <li class="spaced">All variables should be initialised or at
  64 least tested for existence using isset() or empty() before they
  65 are used.</li>
  66 <li class="spaced">All strings should be translatable - create
  67 new texts in the "lang/en" files and call them using get_string()
  68 or print_string().</li>
  69 <li class="spaced">All help files should be translatable - create
  70 new texts in the "en/help" directory and call them using
  71 helpbutton().</li>
  72 </ol>
  73 <p> </p>
  74 <h2>Coding Style</h2>
  75 <p class="normaltext">I know it can be a little annoying to
  76 change your style if you're used to something else, but balance
  77 that annoyance against the annoyance of all the people trying
  78 later on to make sense of Moodle code with mixed styles. There
  79 are obviously many good points for and against any style that
  80 people use, but the current style just <strong>is</strong>, so
  81 please stick to it.</p>
  82 <ol class="normaltext">
  83 <li class="spaced"><strong>Indenting</strong> should be
  84 consistently 4 spaces. Don't use tabs AT ALL.</li>
  85 <li class="spaced"><strong>Variable names</strong> should always
  86 be easy-to-read, meaningful lowercase English words. If you
  87 really need more than one word then run them together, but keep
  88 them short as possible. Use plural names for arrays of objects.
  89 <p class="examplecode"><font color="#006600">GOOD: $quiz<br>
  90 GOOD: $errorstring<br>
  91 GOOD: $assignments (for an array of objects)<br>
  92 GOOD: $i (but only in little loops)<br>
  93 <br>
  94 BAD: $Quiz<br>
  95 BAD: $aReallyLongVariableNameWithoutAGoodReason<br>
  96 BAD: $error_string</font></p>
  97 </li>
  98 <li class="spaced"><strong>Constants</strong> should always be in
  99 upper case, and always start with the name of the module. They
 100 should have words separated by underscores.
 101 <p class="examplecode"><font color=
 102 "#006600">define("FORUM_MODE_FLATOLDEST", 1);</font></p>
 103 </li>
 104 <li class="spaced"><strong>Function names</strong> should be
 105 simple English words, and start with the name of the module to
 106 avoid conflicts between modules. Words should be separated by
 107 underscores. Parameters should always have sensible defaults if
 108 possible. Note there is no space between the function name and
 109 the following (brackets).<br>
 110 <p class="examplecode"><font color="#007700">function</font>
 111 <font color="#0000BB">forum_set_display_mode</font><font color=
 112 "#007700">(</font><font color="#0000BB">$mode</font><font color=
 113 "#007700">=</font><font color="#0000BB">0</font><font color=
 114 "#007700">) {<br>
 115     global</font> <font color="#0000BB">$USER</font><font color=
 116 "#007700">,</font> <font color="#0000BB">$CFG</font><font color=
 117 "#007700">;<br>
 118 <br>
 119     if (</font><font color="#0000BB">$mode</font><font color=
 120 "#007700">) {<br>
 121         </font><font color="#0000BB">$USER</font><font color=
 122 "#007700">-&gt;</font><font color="#0000BB">mode</font>
 123 <font color="#007700">=</font> <font color=
 124 "#0000BB">$mode</font><font color="#007700">;<br>
 125     } else if (empty(</font><font color=
 126 "#0000BB">$USER</font><font color=
 127 "#007700">-&gt;</font><font color=
 128 "#0000BB">mode</font><font color="#007700">)) {<br>
 129         </font><font color="#0000BB">$USER</font><font color=
 130 "#007700">-&gt;</font><font color="#0000BB">mode</font>
 131 <font color="#007700">=</font> <font color=
 132 "#0000BB">$CFG</font><font color=
 133 "#007700">-&gt;</font><font color=
 134 "#0000BB">forum_displaymode</font><font color="#007700">;<br>
 135     }<br>
 136 }</font></p>
 137 </li>
 138 <li class="spaced"><strong>Blocks</strong> must always be
 139 enclosed in curly braces (even if there is only one line). Moodle
 140 uses this style:
 141 <p class="examplecode"><font color="#006600">if
 142 (</font><font color="#0000CC">$quiz</font><font color=
 143 "#006600">-&gt;</font><font color=
 144 "#0000CC">attempts</font><font color="#006600">) {<br>
 145     if (</font><font color="#0000CC">$numattempts</font>
 146 <font color="#006600">&gt;</font> <font color=
 147 "#0000CC">$quiz</font><font color=
 148 "#006600">-&gt;</font><font color=
 149 "#0000CC">attempts</font><font color="#006600">) {<br>
 150         </font><font color="#0000CC">error</font><font color=
 151 "#006600">(</font><font color=
 152 "#0000BB">$strtoomanyattempts</font><font color=
 153 "#006600">,</font> <font color=
 154 "#CC0000">"view.php?id=$cm</font><font color=
 155 "#006600">-&gt;</font><font color=
 156 "#CC0000">id"</font><font color="#006600">);<br>
 157     }<br>
 158 }</font></p>
 159 </li>
 160 <li class="spaced"><strong>Strings</strong> should be defined
 161 using single quotes where possible, for increased speed.<br>
 162 <p class="examplecode"><font color="#006600">$var = 'some text
 163 without any variables';<br>
 164 $var = "with special characters like a new line \n";<br>
 165 $var = 'a very, very long string with a '.$single.' variable in
 166 it';<br>
 167 $var = "some $text with $many variables $within it";</font></p>
 168 </li>
 169 <li class="spaced"><strong>Comments</strong> should use two or
 170 three slashes and line up nicely with the code.
 171 <p class="examplecode"><font color="#006600">function</font>
 172 <font color="#0000BB">forum_get_ratings_mean</font><font color=
 173 "#007700">(</font><font color=
 174 "#0000BB">$postid</font><font color="#007700">,</font>
 175 <font color="#0000BB">$scale</font><font color="#007700">,</font>
 176 <font color="#0000BB">$ratings</font><font color=
 177 "#007700">=</font><font color="#0000BB">NULL</font><font color=
 178 "#007700">) {<br></font> <font color="#FF8000">/// Return the
 179 mean rating of a post given to the current user by others.<br>
 180 /// Scale is an array of possible ratings in the scale<br>
 181 /// Ratings is an optional simple array of actual ratings (just
 182 integers)<br>
 183 <br>
 184     </font><font color="#007700">if (!</font><font color=
 185 "#0000BB">$ratings</font><font color="#007700">) {<br>
 186         </font><font color="#0000BB">$ratings</font> <font color=
 187 "#007700">= array();     </font><font color="#FF8000">//
 188 Initialize the empty array</font><font color="#007700"><br>
 189         if (</font><font color="#0000BB">$rates</font>
 190 <font color="#007700">=</font> <font color=
 191 "#0000BB">get_records</font><font color=
 192 "#007700">(</font><font color=
 193 "#DD0000">"forum_ratings"</font><font color="#007700">,</font>
 194 <font color="#DD0000">"post"</font><font color="#007700">,</font>
 195 <font color="#0000BB">$postid</font><font color="#007700">))
 196 {<br>
 197             </font><font color="#FF8000">// Process each rating
 198 in turn</font><font color="#007700"><br>
 199             foreach (</font><font color="#0000BB">$rates</font>
 200 <font color="#007700">as</font> <font color=
 201 "#0000BB">$rate</font><font color="#007700">) {</font><br>
 202 ....etc</p>
 203 </li>
 204 <li class="spaced"><strong>Space</strong> should be used
 205 liberally - don't be afraid to spread things out a little to gain
 206 some clarity. Generally, there should be one space between
 207 brackets and normal statements, but no space between brackets and
 208 variables or functions:<br>
 209 <p class="examplecode"><font color="#007700">foreach
 210 (</font><font color="#0000BB">$objects</font> <font color=
 211 "#007700">as</font> <font color="#0000BB">$key</font>
 212 <font color="#007700">=&gt;</font> <font color=
 213 "#0000BB">$thing</font><font color="#007700">)</font>
 214 <font color="#006600">{<br></font> <font color=
 215 "#007700">    </font><font color=
 216 "#0000BB">process($thing);</font> <font color="#006600"><br>
 217 }<br>
 218 <br></font> <font color="#007700">if (</font><font color=
 219 "#0000BB">$x</font> <font color="#007700">==</font> <font color=
 220 "#0000BB">$y</font><font color="#007700">)</font> <font color=
 221 "#006600">{<br></font> <font color=
 222 "#007700">    </font><font color="#0000BB">$a</font> <font color=
 223 "#007700">=</font> <font color="#0000BB">$b</font><font color=
 224 "#007700">;</font><font color="#006600"><br>
 225 } else if (</font><font color="#0000BB">$x</font> <font color=
 226 "#007700">==</font> <font color="#0000BB">$z</font><font color=
 227 "#006600">) {<br></font> <font color=
 228 "#007700">    </font><font color="#0000BB">$a</font> <font color=
 229 "#007700">=</font> <font color="#0000BB">$c</font><font color=
 230 "#007700">;</font><font color="#006600"><br>
 231 } else {<br></font> <font color="#007700">    </font><font color=
 232 "#0000BB">$a</font> <font color="#007700">=</font> <font color=
 233 "#0000BB">$d</font><font color="#007700">;</font><font color=
 234 "#006600"><br>
 235 }</font></p>
 236 </li>
 237 </ol>
 238 <p> </p>
 239 <h2>Database structures</h2>
 240 <ol class="normaltext">
 241 <li class="spaced">Every table must have an auto-incrementing
 242 <strong>id</strong> field (INT10) as primary index.</li>
 243 <li class="spaced">The main table containing instances of each
 244 module must have the same name as the module (eg
 245 <strong>widget</strong>) and contain the following minimum
 246 fields:
 247 <ul>
 248 <li><strong>id</strong> - as described above</li>
 249 <li><strong>course</strong> - the id of the course that each
 250 instance belongs to</li>
 251 <li><strong>name</strong> - the full name of each instance of the
 252 module</li>
 253 </ul>
 254 </li>
 255 <li class="spaced">Other tables associated with a module that
 256 contain information about 'things' should be named
 257 <strong>widget_things</strong> (note the plural).</li>
 258 <li class="spaced">Column names should be simple and short,
 259 following the same rules as for variable names.</li>
 260 <li class="spaced">Where possible, columns that contain a
 261 reference to the id field of another table (eg
 262 <strong>widget</strong>) should be called
 263 <strong>widgetid</strong>. (Note that this convention is newish
 264 and not followed in some older tables)</li>
 265 <li class="spaced">Boolean fields should be implemented as small
 266 integer fields (eg INT4) containing 0 or 1, to allow for later
 267 expansion of values if necessary.</li>
 268 <li class="spaced">Most tables should have a
 269 <strong>timemodified</strong> field (INT10) which is updated with
 270 a current timestamp obtained with the PHP <strong>time</strong>()
 271 function.</li>
 272 </ol>
 273 <hr>
 274 <p align="center"><a href="." target="_top"><font size="1">Moodle
 275 Documentation</font></a></p>
 276 <p align="center"><font size="1">Version: $Id$</font></p>
 277 </body>
 278 </html>