mirror of
https://github.com/moodle/moodle.git
synced 2025-02-23 11:27:51 +01:00
c1a0356dc7
In the theme "standardxhtml" I added a stylesheet file "docstyles.php" to overwrite the theme independend "docstyles.css".
279 lines
12 KiB
HTML
279 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
<title>Moodle Dokumentation: Coding Guidelines</title>
|
||
<link rel="stylesheet" href="docstyles.css" type="TEXT/CSS">
|
||
<script language="JavaScript" type="text/javascript">
|
||
<!-- //hide
|
||
var themeCSS = "<?php echo "$CFG->wwwroot/theme/$CFG->theme" ?>";
|
||
if (themeCSS.indexOf("CFG->wwwroot") != true) {
|
||
document.write ("<link rel=\"stylesheet\" type=\"text/css\" href=\"" + themeCSS +"/styles.php\" />");
|
||
document.write ("<link rel=\"stylesheet\" type=\"text/css\" href=\"" + themeCSS +"/docstyles.php\" />");
|
||
}
|
||
// done hiding -->
|
||
</script>
|
||
<meta http-equiv="Content-Type" content=
|
||
"text/html; charset=us-ascii">
|
||
</head>
|
||
<body bgcolor="#FFFFFF">
|
||
<h1>Moodle Coding Guidelines</h1>
|
||
<p class="normaltext">Die Stabilität eines Programms wie
|
||
Moodle hängt weesentlich davon ab, dass alle Entwickler des
|
||
Programmcodes bestimmte Grundregeln einheitlich anwenden. Diese
|
||
sind hier definert.</p>
|
||
<p class="normaltext">Dieser Text wird vorläufig nicht ins
|
||
Deutsche übersetzt. Wir gehen davon aus, dass alle Anwender,
|
||
die selber Programmteile für Moodle bearbeiten wollen so
|
||
viel Englisch lesen und verstehen können dass sie diesen
|
||
Text im Original verstehen.</p>
|
||
<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>General Rules</h2>
|
||
<ol class="normaltext">
|
||
<li class="spaced">All code files should use the .php
|
||
extension.</li>
|
||
<li class="spaced">All template files should use the .html
|
||
extension.</li>
|
||
<li class="spaced">All text files should use Unix-style text
|
||
format (most text editors have this as an option).</li>
|
||
<li class="spaced">All php tags must be 'full' tags like
|
||
<font color="#339900"><?php ?></font> ... not 'short' tags
|
||
like <font color="#339900"><? ?></font>.</li>
|
||
<li class="spaced">All existing copyright notices must be
|
||
retained. You can add your own if necessary.</li>
|
||
<li class="spaced">Each file should include the main config.php
|
||
file.</li>
|
||
<li class="spaced">Each file should check that the user is
|
||
authenticated correctly, using require_login() and isadmin(),
|
||
isteacher(), iscreator() or isstudent().</li>
|
||
<li class="spaced">All access to databases should use the
|
||
functions in lib/datalib.php whenever possible - this allows
|
||
compatibility across a wide range of databases. You should find
|
||
that almost anything is possible using these functions. If you
|
||
must write SQL code then make sure it is: cross-platform;
|
||
restricted to specific functions within your code (usually a
|
||
lib.php file); and clearly marked.</li>
|
||
<li class="spaced">Don't create or use global variables except
|
||
for the standard $CFG, $SESSION, $THEME and $USER.</li>
|
||
<li class="spaced">All variables should be initialised or at
|
||
least tested for existence using isset() or empty() before they
|
||
are used.</li>
|
||
<li class="spaced">All strings should be translatable - create
|
||
new texts in the "lang/en" files and call them using get_string()
|
||
or print_string().</li>
|
||
<li class="spaced">All help files should be translatable - create
|
||
new texts in the "en/help" directory and call them using
|
||
helpbutton().</li>
|
||
</ol>
|
||
<p><EFBFBD></p>
|
||
<h2>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 class="spaced"><strong>Indenting</strong> should be
|
||
consistently 4 spaces. Don't use tabs AT ALL.</li>
|
||
<li class="spaced"><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. Use plural names for arrays of objects.
|
||
<p class="examplecode"><font color="#006600">GOOD: $quiz<br>
|
||
GOOD: $errorstring<br>
|
||
GOOD: $assignments (for an array of objects)<br>
|
||
GOOD: $i (but only in little loops)<br>
|
||
<br>
|
||
BAD: $Quiz<br>
|
||
BAD: $aReallyLongVariableNameWithoutAGoodReason<br>
|
||
BAD: $error_string</font></p>
|
||
</li>
|
||
<li class="spaced"><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 class="spaced"><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>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD>global</font> <font color="#0000BB">$USER</font><font color=
|
||
"#007700">,</font> <font color="#0000BB">$CFG</font><font color=
|
||
"#007700">;<br>
|
||
<br>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD>if (</font><font color="#0000BB">$mode</font><font color=
|
||
"#007700">) {<br>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD></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>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD>} else if (empty(</font><font color=
|
||
"#0000BB">$USER</font><font color=
|
||
"#007700">-></font><font color=
|
||
"#0000BB">mode</font><font color="#007700">)) {<br>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD></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>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD>}<br>
|
||
}</font></p>
|
||
</li>
|
||
<li class="spaced"><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>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD>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>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD></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>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD>}<br>
|
||
}</font></p>
|
||
</li>
|
||
<li class="spaced"><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 class="spaced"><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>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD></font><font color="#007700">if (!</font><font color=
|
||
"#0000BB">$ratings</font><font color="#007700">) {<br>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD></font><font color="#0000BB">$ratings</font> <font color=
|
||
"#007700">= array(); <20><><EFBFBD><EFBFBD></font><font color="#FF8000">//
|
||
Initialize the empty array</font><font color="#007700"><br>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>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>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD></font><font color="#FF8000">// Process each rating
|
||
in turn</font><font color="#007700"><br>
|
||
<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>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 class="spaced"><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"><EFBFBD><EFBFBD><EFBFBD><EFBFBD></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"><EFBFBD><EFBFBD><EFBFBD><EFBFBD></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"><EFBFBD><EFBFBD><EFBFBD><EFBFBD></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"><EFBFBD><EFBFBD><EFBFBD><EFBFBD></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><EFBFBD></p>
|
||
<h2>Database structures</h2>
|
||
<ol class="normaltext">
|
||
<li class="spaced">Every table must have an auto-incrementing
|
||
<strong>id</strong> field (INT10) as primary index.</li>
|
||
<li class="spaced">The main table containing instances of each
|
||
module must have the same name as the module (eg
|
||
<strong>widget</strong>) and contain the following minimum
|
||
fields:
|
||
<ul>
|
||
<li><strong>id</strong> - as described above</li>
|
||
<li><strong>course</strong> - the id of the course that each
|
||
instance belongs to</li>
|
||
<li><strong>name</strong> - the full name of each instance of the
|
||
module</li>
|
||
</ul>
|
||
</li>
|
||
<li class="spaced">Other tables associated with a module that
|
||
contain information about 'things' should be named
|
||
<strong>widget_things</strong> (note the plural).</li>
|
||
<li class="spaced">Column names should be simple and short,
|
||
following the same rules as for variable names.</li>
|
||
<li class="spaced">Where possible, columns that contain a
|
||
reference to the id field of another table (eg
|
||
<strong>widget</strong>) should be called
|
||
<strong>widgetid</strong>. (Note that this convention is newish
|
||
and not followed in some older tables)</li>
|
||
<li class="spaced">Boolean fields should be implemented as small
|
||
integer fields (eg INT4) containing 0 or 1, to allow for later
|
||
expansion of values if necessary.</li>
|
||
<li class="spaced">Most tables should have a
|
||
<strong>timemodified</strong> field (INT10) which is updated with
|
||
a current timestamp obtained with the PHP <strong>time</strong>()
|
||
function.</li>
|
||
</ol>
|
||
<hr>
|
||
<p align="center"><a href="." target="_top"><font size="1">Moodle
|
||
Documentation</font></a></p>
|
||
<p align="center"><font size="1">Version: $Id$</font></p>
|
||
</body>
|
||
</html>
|