<html>\r
-\r
<head>\r
<title>Moodle Docs: Coding Guidelines</title>\r
<link rel="stylesheet" href="../theme/standard/styles.php" type="TEXT/CSS">\r
-->\r
</style>\r
</head>\r
-\r
-\r
-\r
<body bgcolor="#FFFFFF">\r
-\r
<h2>Moodle Coding Guidelines</h2>\r
-\r
+<p class="normaltext">Any collaborative project needs consistency and stability \r
+ to stay strong.</p>\r
+<p class="normaltext">These guidelines are to provide a goal for all Moodle code \r
+ to strive to. It's true that some of the older existing code falls short in \r
+ a few areas, but it will all be fixed eventually. All new code definitely must \r
+ adhere to these standards as closely as possible.</p>\r
<h2 class="normaltext">General Rules</h2>\r
- \r
<ol class="normaltext">\r
- <li>All files should use the .php extension.</li>\r
+ <li>All code files should use the .php extension.</li>\r
+ <li>All template files should use the .html extension.</li>\r
+ <li>All text files should use Unix-style text format (most text editors have \r
+ this as an option).</li>\r
+ <li>All php tags should be 'full' tags like <font color="#339900"><?php</font> \r
+ - short tags are not allowed. </li>\r
<li>All existing copyright notices must be retained. You can add your own if \r
necessary.</li>\r
<li>Each file should include the main config.php file.</li>\r
should find that almost anything is possible using these functions. Any other \r
SQL statements should be: cross-platform; restricted to specific functions \r
within your code (usally a lib.php file); and clearly marked.</li>\r
+ <li>Don't create or use global variables except for the standard $CFG, $SESSION, \r
+ $THEME and $USER.</li>\r
+ <li>All variables should be initialised or at least tested for existence using \r
+ isset() or empty() before they are used.</li>\r
<li>All strings should be translatable - create new texts in the "lang/en" \r
files and call them using get_string() or print_string().</li>\r
<li>All help files should be translatable - create new texts in the "en/help" \r
</ol>\r
<p> </p>\r
<h2 class="normaltext">Coding Style</h2>\r
- \r
+<p class="normaltext">I know it can be a little annoying to change your style \r
+ if you're used to something else, but balance that annoyance against the annoyance \r
+ of all the people trying later on to make sense of Moodle code with mixed styles. \r
+ There are obviously many good points for and against any style that people use, \r
+ but the current style just <strong>is</strong>, so please stick to it. </p>\r
<ol class="normaltext">\r
- <li>Don't use tabs at all. Use consistent indenting with 4 spaces.</li>\r
- <li>Braces must always be used for blocks of code (even if there is only one \r
- line). Moodle uses this style: \r
+ <li><strong>Indenting</strong> should be consistently 4 spaces. Don't use tabs \r
+ AT ALL. </li>\r
+ <li><strong>Variable names</strong> should always be easy-to-read, meaningful \r
+ lowercase English words. If you really need more than one word then run them \r
+ together, but keep them short as possible. \r
+ <p class="examplecode"><font color="#006600">GOOD: $quiz<br>\r
+ GOOD: $errorstring<br>\r
+ GOOD: $i (but only in little loops)<br>\r
+ <br />\r
+ BAD: $Quiz <br>\r
+ BAD: $aReallyLongVariableNameWithoutAGoodReason<br>\r
+ BAD: $error_string</font></p>\r
+ </li>\r
+ <li><strong>Constants</strong> should always be in upper case, and always start \r
+ with the name of the module. They should have words separated by underscores. \r
+ <p class="examplecode"><font color="#006600">define("FORUM_MODE_FLATOLDEST", \r
+ 1);</font></p>\r
+ </li>\r
+ <li><strong>Function names</strong> should be simple English words, and start \r
+ with the name of the module to avoid conflicts between modules. Words should \r
+ be separated by underscores. Parameters should always have sensible defaults \r
+ if possible. Note there is no space between the function name and the following \r
+ (brackets). <br>\r
+ <p class="examplecode"> <font color="#007700">function </font><font color="#0000BB">forum_set_display_mode</font><font color="#007700">(</font><font color="#0000BB">$mode</font><font color="#007700">=</font><font color="#0000BB">0</font><font color="#007700">) \r
+ {<br />\r
+ global </font><font color="#0000BB">$USER</font><font color="#007700">, \r
+ </font><font color="#0000BB">$CFG</font><font color="#007700">;<br />\r
+ <br />\r
+ if (</font><font color="#0000BB">$mode</font><font color="#007700">) \r
+ {<br />\r
+ </font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode \r
+ </font><font color="#007700">= </font><font color="#0000BB">$mode</font><font color="#007700">;<br />\r
+ } else if (empty(</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode</font><font color="#007700">)) \r
+ {<br />\r
+ </font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode \r
+ </font><font color="#007700">= </font><font color="#0000BB">$CFG</font><font color="#007700">-></font><font color="#0000BB">forum_displaymode</font><font color="#007700">;<br />\r
+ }<br />\r
+ }</font></p>\r
+ </li>\r
+ <li><strong>Blocks</strong> must always be enclosed in curly braces (even if \r
+ there is only one line). Moodle uses this style: \r
<p class="examplecode"> <font color="#006600">if (</font><font color="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">) \r
{<br />\r
if (</font><font color="#0000CC">$numattempts </font><font color="#006600">> \r
</font><font color="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">) \r
{<br />\r
- </font><font color="#0000CC">error</font><font color="#006600">(</font><font color="#CC0000">$strtoomanyattempts</font><font color="#006600">, \r
+ </font><font color="#0000CC">error</font><font color="#006600">(</font><font color="#0000BB">$strtoomanyattempts</font><font color="#006600">, \r
</font><font color="#CC0000">"view.php?id=$cm</font><font color="#006600">-></font><font color="#CC0000">id"</font><font color="#006600">);<br />\r
}<br />\r
}</font></p>\r
</li>\r
- <li>more to come here .... this document is not nearly finished yet!</li>\r
- </ol>\r
-\r
-\r
-\r
+ <li><strong>Strings</strong> should be defined using single quotes where possible, \r
+ for increased speed.<br>\r
+ <p class="examplecode"> <font color="#006600">$var = 'some text without any \r
+ variables';<br>\r
+ $var = "with special characters like a new line \n";<br>\r
+ $var = 'a very, very long string with a '.$single.' variable in it';<br>\r
+ $var = "some $text with $many variables $within it"; </font></p>\r
+ </li>\r
+ <li><strong>Comments</strong> should use two or three slashes and line up nicely \r
+ with the code. \r
+ <p class="examplecode"><font color="#006600">function </font><font color="#0000BB">forum_get_ratings_mean</font><font color="#007700">(</font><font color="#0000BB">$postid</font><font color="#007700">, \r
+ </font><font color="#0000BB">$scale</font><font color="#007700">, </font><font color="#0000BB">$ratings</font><font color="#007700">=</font><font color="#0000BB">NULL</font><font color="#007700">) \r
+ {<br />\r
+ </font><font color="#FF8000">/// Return the mean rating of a post given \r
+ to the current user by others.<br />\r
+ /// Scale is an array of possible ratings in the scale<br />\r
+ /// Ratings is an optional simple array of actual ratings (just integers)<br />\r
+ <br />\r
+ </font><font color="#007700">if (!</font><font color="#0000BB">$ratings</font><font color="#007700">) \r
+ {<br />\r
+ </font><font color="#0000BB">$ratings \r
+ </font><font color="#007700">= array(); </font><font color="#FF8000">// \r
+ Initialize the empty array</font><font color="#007700"><br />\r
+ if (</font><font color="#0000BB">$rates \r
+ </font><font color="#007700">= </font><font color="#0000BB">get_records</font><font color="#007700">(</font><font color="#DD0000">"forum_ratings"</font><font color="#007700">, \r
+ </font><font color="#DD0000">"post"</font><font color="#007700">, </font><font color="#0000BB">$postid</font><font color="#007700">)) \r
+ {<br>\r
+ </font><font color="#FF8000">// \r
+ Process each rating in turn</font><font color="#007700"><br />\r
+ foreach \r
+ (</font><font color="#0000BB">$rates </font><font color="#007700">as </font><font color="#0000BB">$rate</font><font color="#007700">) \r
+ {</font> <br>\r
+ ....etc </p>\r
+ </li>\r
+ <li><strong>Space</strong> should be used liberally - don't be afraid to spread \r
+ things out a little to gain some clarity. Generally, there should be one space \r
+ between brackets and normal statements, but no space between brackets and \r
+ variables or functions:<br>\r
+ <p class="examplecode"> <font color="#007700">foreach (</font><font color="#0000BB">$objects \r
+ </font><font color="#007700">as </font><font color="#0000BB">$key </font><font color="#007700">=></font><font color="#0000BB"> \r
+ $thing</font><font color="#007700">)</font><font color="#006600"> {<br>\r
+ </font><font color="#007700"> </font><font color="#0000BB">process($thing);</font><font color="#006600"> \r
+ <br>\r
+ } <br>\r
+ <br>\r
+ </font><font color="#007700">if (</font><font color="#0000BB">$x </font><font color="#007700">== \r
+ </font><font color="#0000BB">$y</font><font color="#007700">)</font><font color="#006600"> \r
+ {<br>\r
+ </font><font color="#007700"> </font><font color="#0000BB">$a \r
+ </font><font color="#007700">= </font><font color="#0000BB">$b</font><font color="#007700">;</font><font color="#006600"><br>\r
+ } else if (</font><font color="#0000BB">$x </font><font color="#007700">== \r
+ </font><font color="#0000BB">$z</font><font color="#006600">) {<br>\r
+ </font><font color="#007700"> </font><font color="#0000BB">$a \r
+ </font><font color="#007700">= </font><font color="#0000BB">$c</font><font color="#007700">;</font><font color="#006600"><br>\r
+ } else {<br>\r
+ </font><font color="#007700"> </font><font color="#0000BB">$a \r
+ </font><font color="#007700">= </font><font color="#0000BB">$d</font><font color="#007700">;</font><font color="#006600"><br>\r
+ } </font></p>\r
+ </li>\r
+</ol>\r
<p align="center" class="normaltext"> </p>\r
-\r
<hr>\r
<p align="CENTER"><font size="1"><a href="." target="_top">Moodle Documentation</a></font></p>\r
-\r
<p align="CENTER"><font size="1">Version: $Id: faq.html,v 1.6 2003/03/30 13:54:28 \r
-\r
moodler Exp $</font></p>\r
-\r
-\r
-\r
</body>\r
-\r
</html>\r
-\r
projects / moodle.git / commitdiff