Development:Coding draft - Revision history

Dougiamas: /* Coding Style */

2008-11-24T07:45:31Z

Coding Style

← Older revision		Revision as of 07:45, 24 November 2008
Line 130:		Line 130:

	==Coding Style==		==Coding Style==
	~~===PHP Code Demarcation===~~
	===Strings===		===Strings===
	====String ~~Literals~~====
	====~~String Literals Containing Apostrophes~~====		Since performance is not such an issue in current versions of PHP, the main criteria with strings is readability.
	====Variable ~~Substitution~~====
	====String ~~Concatenation~~====
			====Single quotes====

			Always use single quotes when a string is literal, or contains a lot of double quotes (like HTML):

			<code php>
			$a = 'Example String';
			echo '<span class="'.s($class).'"></span>';
			$html = '<a href="http://something" title="something">Link</a>';
			</code>

			====Double quotes====

			These are a lot less useful in Moodle.

			Use double quotes when you need to include plain variables or a lot of single quotes. In Moodle 2.0 or later you won't need to be doing a lot of single quotes for SQL so that's not an issue.

			<code php>
			echo "<span>$string</span>";
			$statement = "You aren't serious!";
			</code>

			====Variable substitution====

			====String concatenation====


	===Arrays===		===Arrays===
	====Numerically ~~Indexed Arrays~~====		====Numerically indexed arrays====
	====Associative ~~Arrays~~====		====Associative arrays====
	===Classes===		===Classes===
	====Class ~~Declarations~~====		====Class declarations====
	====Class ~~Member Variables~~====		====Class member variables====
	===Functions and ~~Methods~~===		===Functions and methods===
	====Function and ~~Method Declaration~~====		====Function and method declaration====
	====Function and ~~Method Usage~~====		====Function and method usage====
	===Control ~~Statements~~===		===Control statements===
	====If / ~~Else~~====		====If / else====
	====Switch====		====Switch====
	===Inline ~~Documentation~~===
	====Documentation ~~Format~~====		===Inline documentation===
			====Documentation format====
	====Files====		====Files====
	====Classes====		====Classes====
	====Functions====		====Functions====
	====Require / ~~Include~~====		====Require / include====

	==Errors and Exceptions==		==Errors and Exceptions==
	====Exception best practices====		====Exception best practices====

Dougiamas: /* Booleans and the NULL Value */

2008-11-24T05:12:09Z

Booleans and the NULL Value

← Older revision		Revision as of 05:12, 24 November 2008
Line 126:		Line 126:

	===Booleans and the NULL Value===		===Booleans and the NULL Value===

			Use lower case for '''true''', '''false''' and '''null'''.

	==Coding Style==		==Coding Style==

Dougiamas: /* Constants */

2008-11-24T05:10:05Z

Constants

← Older revision		Revision as of 05:10, 24 November 2008
Line 119:		Line 119:

	===Constants===		===Constants===

			Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.
			<code php>
			define("FORUM_MODE_FLATOLDEST", 1);
			</code>

	===Booleans and the NULL Value===		===Booleans and the NULL Value===

Dougiamas: /* Variables */

2008-11-24T05:09:26Z

Variables

@@ Line 106: / Line 106: @@
 ===Variables===
 ===Constants===
 ===Booleans and the NULL Value===

Dougiamas: /* PHP tags */

2008-11-24T05:08:00Z

PHP tags

← Older revision		Revision as of 05:08, 24 November 2008
Line 24:		Line 24:
	===PHP tags===		===PHP tags===

	Always use ~~full~~ php tags: ~~'''<?php'''~~		Always use "long" php tags. However, to avoid whitespace problems, DO NOT include the closing tag at the very end of the file.

	~~To avoid whitespace problems, DO NOT~~ include ~~the closing tag at the end: '~~''?>~~'''~~		<code php>
			<?php

			include('config.php');

			</code>

	===Indentation===		===Indentation===

Dougiamas: /* PHP tags */

2008-11-24T05:05:20Z

PHP tags

← Older revision		Revision as of 05:05, 24 November 2008
Line 24:		Line 24:
	===PHP tags===		===PHP tags===

	Always use full php tags: <?php		Always use full php tags: '''<?php'''

	To avoid whitespace problems, DO NOT include the closing tag at the end: ?>		To avoid whitespace problems, DO NOT include the closing tag at the end: '''?>'''

	===Indentation===		===Indentation===

Dougiamas: /* General */

2008-11-24T05:05:02Z

General

← Older revision		Revision as of 05:05, 24 November 2008
Line 22:		Line 22:
	==File Formatting==		==File Formatting==

	===~~General~~===		===PHP tags===

	~~For files that contain only PHP code~~, ~~leave out~~ the closing tag ("?>~~"). It is not required by PHP, and omitting it prevents trailing whitespace from being accidentally injected into the output.~~		Always use full php tags: <?php

			To avoid whitespace problems, DO NOT include the closing tag at the end: ?>

	===Indentation===		===Indentation===

Dougiamas: /* Goals */

2008-11-24T05:02:29Z

Goals

← Older revision		Revision as of 05:02, 24 November 2008
Line 13:		Line 13:
	Abstract goals we strive for:		Abstract goals we strive for:

	* extreme simplicity		* extreme simplicity
	* tool friendliness, such as use of method signatures, constants, and patterns that support IDE tools and auto-completion of method, class, and constant names.		* tool friendliness, such as use of method signatures, constants, and patterns that support IDE tools and auto-completion of method, class, and constant names.

	When considering the goals above, each situation requires an examination of the circumstances and balancing of various trade-offs.		When considering the goals above, each situation requires an examination of the circumstances and balancing of various trade-offs.

Dougiamas at 05:02, 24 November 2008

2008-11-24T05:02:00Z

← Older revision		Revision as of 05:02, 24 November 2008
Line 1:		Line 1:
	This is a new draft of the coding guidelines that I'm working on. The structure was based on [http://framework.zend.com/manual/en/coding-standard.html]		This is a new draft of the coding guidelines that I'm working on. The structure was based on [http://framework.zend.com/manual/en/coding-standard.html the Zend guidelines] and our old [[Development:Coding]] page.

Dougiamas: Getting started ...

2008-11-24T02:16:19Z

Getting started ...

New page

This is a new draft of the coding guidelines that I'm working on. The structure was based on [http://framework.zend.com/manual/en/coding-standard.html]

==Overview==
===Scope===

This document describes coding standards and guidelines for developers working on or with Moodle.

===Goals===

Good coding standards are important in any development project, particularly when multiple developers are working on the same project. Having coding standards helps to ensure that the code is of high quality, has fewer bugs, and is easily maintained.

Abstract goals we strive for:

* extreme simplicity
* tool friendliness, such as use of method signatures, constants, and patterns that support IDE tools and auto-completion of method, class, and constant names.

When considering the goals above, each situation requires an examination of the circumstances and balancing of various trade-offs.

Note that much of the existing Moodle code may not follow all of these guidelines - we continue to upgrade this code when we see it.

==File Formatting==

===General===

For files that contain only PHP code, leave out the closing tag ("?>"). It is not required by PHP, and omitting it prevents trailing whitespace from being accidentally injected into the output.

===Indentation===

Use an indent of 4 spaces with no tab characters. Editors should be configured to treat tabs as spaces in order to prevent injection of new tab characters into the source code.

===Maximum Line Length===

Aim for 80 characters if it is convenient. However, you can go longer if it helps overall readability. The maximum line length is 120 characters.

===Line Termination===

Use standard Unix text format. Lines must end only with a linefeed (LF). Linefeeds are represented as ordinal 10, or hexadecimal 0x0A.

Do not use carriage returns (CR) like Macintosh computers (0x0D).

Do not use the carriage return/linefeed combination (CRLF) as Windows computers (0x0D, 0x0A).

Lines should not contain trailing spaces. In order to facilitate this convention, most editors can be configured to strip trailing spaces, such as upon a save operation.

==Naming Conventions==

===Filenames===

Filenames should :
* be whole english words
* be as short as possible
* use lowercase letters only
* end in .php, .html, .js, or .xml

===Classes===

Class names should always be lowercase english words, separated by underscores:

<code php>
class some_custom_class {
function class_method() {
echo "foo";
}
}
</code>

===Functions and Methods===

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.

Verbosity is encouraged: function names should be as illustrative as is practical to enhance understanding.

Note there is no space between the function name and the following (brackets).

<code php>
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;
}
}
</code>

====Function Parameters====

Parameters are always simple lowercase English words (sometimes more than one, like $initialvalue), and should always have sensible defaults if possible.

Use "null" as the default value instead of "false", for situations like this where a default value isn't needed.
<code php>
public function foo($required, $optional = null)
</code>

However, if an optional parameter is boolean, and its logical default value should be true, or false, then using true or false is acceptable.

===Variables===
===Constants===
===Booleans and the NULL Value===

==Coding Style==
===PHP Code Demarcation===
===Strings===
====String Literals====
====String Literals Containing Apostrophes====
====Variable Substitution====
====String Concatenation====
===Arrays===
====Numerically Indexed Arrays====
====Associative Arrays====
===Classes===
====Class Declarations====
====Class Member Variables====
===Functions and Methods===
====Function and Method Declaration====
====Function and Method Usage====
===Control Statements===
====If / Else====
====Switch====
===Inline Documentation===
====Documentation Format====
====Files====
====Classes====
====Functions====
====Require / Include====

==Errors and Exceptions==
====Exception best practices====