Moodle Docs: Coding Guidelines

From: moodler Date: Sun, 28 Sep 2003 15:56:58 +0000 (+0000) Subject: Getting there ... still working on it. X-Git-Url: http://git.mjollnir.org/gw?a=commitdiff_plain;h=d85ce97e99149046d30f94cb26bbf117be599161;p=moodle.git Getting there ... still working on it. --- diff --git a/lang/en/docs/coding.html b/lang/en/docs/coding.html index 8122605ba7..a50830f15d 100755 --- a/lang/en/docs/coding.html +++ b/lang/en/docs/coding.html @@ -1,5 +1,4 @@ - Moodle Docs: Coding Guidelines @@ -100,17 +99,22 @@ li { --> - - - -

Moodle Coding Guidelines

- +

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.

General Rules

All files should use the .php extension.
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 should be 'full' tags like <?php + - short tags are not allowed.
All existing copyright notices must be retained. You can add your own if necessary.
Each file should include the main config.php file.
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 and call them using get_string() or print_string().
All help files should be translatable - create new texts in the "en/help" @@ -128,38 +136,127 @@ li {

Coding Style

- +

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.

Don't use tabs at all. Use consistent indenting with 4 spaces.
Braces must always be used for blocks of code (even if there is only one - line). Moodle uses this style: +
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. +
GOOD: $quiz
+ GOOD: $errorstring
+ 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 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, +         error($strtoomanyattempts, "view.php?id=$cm->id");
    }
}
more to come here .... this document is not nearly finished yet!

- - - +

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;
+ }

Moodle Documentation

Version: $Id: faq.html,v 1.6 2003/03/30 13:54:28 - moodler Exp $

- - - - -