Any collaborative project needs consistency and stability
to stay strong.
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.
- All code files should use the .php extension.
- All template files should use the .html extension.
- All text files should use Unix-style text format (most text
editors have this as an option).
- All php tags must be 'full' tags like <?php
?> ... not 'short' tags like <? ?>.
- All existing copyright notices must be retained. You can
add your own if necessary.
- Each file should include the main config.php file.
- Each file should check that the user is authenticated correctly,
using require_login() and isadmin(), isteacher(), iscreator() or isstudent().
- 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.
- Don't create or use global variables except for the standard
$CFG, $SESSION, $THEME and $USER.
- All variables should be initialised or at least tested for
existence using isset() or empty() before they are used.
- All strings should be translatable - create new texts in
the "lang/en" files with concise English lowercase names and retrieve them
from your code using get_string() or print_string().
- All help files should be translatable - create new texts
in the "en/help" directory and call them using helpbutton().
If you need to update a help file:
- with a minor change, where an old translation of the
file would still make sense, then it's OK to make the change
but you should notify translation@moodle.org
- for a major change you should create a new file by adding
an incrementing number (eg filename2.html) so that translators
can easily see it's a new version of the file. Obviously the
new code and the help index files should also be modified to point
to the newest versions.
- Incoming data from the browser (sent via GET or POST) automatically
has magic_quotes applied (regardless of the PHP settings) so that you can safely
insert it straight into the database. All other raw data (from files, or from databases)
must be escaped with addslashes() before inserting it into the database.
- IMPORTANT: All texts within Moodle, especially those that have
come from users, should be printed using the format_text() function. This ensures that
text is filtered and cleaned correctly.
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 is, so please stick to it.
- Indenting should be consistently 4 spaces.
Don't use tabs AT ALL.
- Variable names 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.
GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)
BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string
- Constants should always be in upper case,
and always start with the name of the module. They should have words separated
by underscores.
define("FORUM_MODE_FLATOLDEST",
1);
- Function names should be simple English
lowercase 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).
function forum_set_display_mode($mode=0)
{
global $USER,
$CFG;
if ($mode)
{
$USER->mode
= $mode;
} else if (empty($USER->mode))
{
$USER->mode
= $CFG->forum_displaymode;
}
}
- Blocks must always be enclosed in curly
braces (even if there is only one line). Moodle uses this style:
if ($quiz->attempts)
{
if ($numattempts >
$quiz->attempts)
{
error($strtoomanyattempts,
"view.php?id=$cm->id");
}
}
- Strings should be defined using single quotes
where possible, for increased speed.
$var = 'some text without any
variables';
$var = "with special characters like a new line \n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";
- Comments should use two or three slashes
and line up nicely with the code.
function forum_get_ratings_mean($postid,
$scale, $ratings=NULL)
{
/// Return the mean rating of a post given
to the current user by others.
/// Scale is an array of possible ratings in the scale
/// Ratings is an optional simple array of actual ratings (just integers)
if (!$ratings)
{
$ratings
= array(); //
Initialize the empty array
if ($rates
= get_records("forum_ratings",
"post", $postid))
{
//
Process each rating in turn
foreach
($rates as $rate)
{
....etc
- Space 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:
foreach ($objects
as $key =>
$thing) {
process($thing);
}
if ($x ==
$y)
{
$a
= $b;
} else if ($x ==
$z) {
$a
= $c;
} else {
$a
= $d;
}