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