Coding Guidelines - Revision history

Dirk: added link to Commit Messages page

2010-03-13T13:09:07Z

added link to Commit Messages page

Dirk: link to Mercurial setup for correct line endings

2010-01-30T19:58:25Z

link to Mercurial setup for correct line endings

Dirk: added a link to Best Practices

2010-01-30T19:54:36Z

added a link to Best Practices

Dirk: added a link to Source Code Documentation

2009-06-05T09:55:29Z

added a link to Source Code Documentation

Dirk: Mostly cosmetics

2009-05-05T13:14:42Z

Mostly cosmetics

Dirk: Added category

2008-03-07T13:02:06Z

Added category

Dirk: Added the pieces of the PEAR Coding Standards that we're adopting

2007-03-03T13:55:07Z

Added the pieces of the PEAR Coding Standards that we're adopting

Dirk: Added links to the original pages at pear.php.net

2007-03-03T13:39:56Z

Added links to the original pages at pear.php.net

Dirk: New Coding Guidelines, mostly following the PEAR Coding Standards

2007-03-03T13:35:25Z

New Coding Guidelines, mostly following the PEAR Coding Standards

Dirk: Typos

2007-01-13T21:30:39Z

Typos

← Older revision		Revision as of 13:09, 13 March 2010
Line 192:		Line 192:

	* [[Best Practices]]		* [[Best Practices]]
		+	* [[Commit Messages]]


	[[Category:Development]]		[[Category:Development]]

← Older revision		Revision as of 19:58, 30 January 2010
Line 185:		Line 185:
	*# Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.		*# Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
	*# There should be one line feed after the closing PHP tag (<code>?></code>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.		*# There should be one line feed after the closing PHP tag (<code>?></code>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.
		+
		+	You can [[Using Mercurial#Windows_vs._Unix_Line_Endings\|configure Mercurial]] such that it won't allow you to commit files with the "wrong" line endings.

@@ Line 5: / Line 5: @@
 == Why have Code Conventions? ==
 Code conventions are important to programmers for a number of reasons:
@@ Line 187: / Line 185: @@
 *# Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
 *# There should be one line feed after the closing PHP tag (<code>?></code>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.
 [[Category:Development]]

@@ Line 10: / Line 10: @@
 Code conventions are important to programmers for a number of reasons:
-* 80% of the lifetime cost of apiece of software goes to maintenance.
+* 80% of the lifetime cost of a piece of software goes to maintenance.
 * Hardly any software is maintained for its whole life by the original author.
 * Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly. If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
@@ Line 159: / Line 159: @@
 === Comments ===
-Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks (''to be defined'' - [[User:Dirk|Dirk]]) sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. Further information can be found on the [http://www.phpdoc.org/ phpDocumentor website].
+Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks (''to be defined'' - [[User:Dirk|Dirk]]) sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. For further information see [[Source Code Documentation]] and the [http://www.phpdoc.org/ phpDocumentor website].
 Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.
-C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.
+C style comments (<code>/* */</code>) and standard C++ comments (<code>//</code>) are both fine. Use of Perl/shell style comments (<code>#</code>) is discouraged.

@@ Line 1: / Line 1: @@
-= Coding Guidelines for Geeklog 1.x =
+= Coding Guidelines for Geeklog =
-Geeklog 1.x never had any formal coding guidelines so you may find different styles in different places. '''As of March 2007, all new code in Geeklog will have to follow the PEAR coding standards''' (see below for details).
+Geeklog originally didn't have any formal coding guidelines and so you may find different coding styles in different places. '''As of March 2007, all new code in Geeklog will have to follow the PEAR coding standards''' (see below for details).
@@ Line 159: / Line 159: @@
 === Comments ===
-Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks (''to be defined'' - [[User:Dirk|Dirk]]} sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. Further information can be found on the phpDocumentor website.
+Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks (''to be defined'' - [[User:Dirk|Dirk]]) sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. Further information can be found on the [http://www.phpdoc.org/ phpDocumentor website].
 Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

← Older revision		Revision as of 13:55, 3 March 2007
Line 41:		Line 41:

	To be defined: "Header Comment Blocks" [http://pear.php.net/manual/en/standards.header.php (9)]. It may also make sense to adopt "E_STRICT-compatible code" [http://pear.php.net/manual/en/standards.e_strict.php (10)] but that may be difficult to achieve in some contexts. It should certainly become a long-term goal, though.		To be defined: "Header Comment Blocks" [http://pear.php.net/manual/en/standards.header.php (9)]. It may also make sense to adopt "E_STRICT-compatible code" [http://pear.php.net/manual/en/standards.e_strict.php (10)] but that may be difficult to achieve in some contexts. It should certainly become a long-term goal, though.
		+
		+
		+	== Coding Guidelines ==
		+
		+	=== Indenting and Line Length ===
		+
		+	Use an indent of 4 spaces, with '''no tabs'''. This helps to avoid problems with diffs, patches, CVS history and annotations.
		+
		+	For Emacs you should set indent-tabs-mode to nil. Here is an example mode hook that will set up Emacs (ensure that it is called when you are editing PHP files):
		+
		+	<pre>(defun php-mode-hook ()
		+	(setq tab-width 4
		+	c-basic-offset 4
		+	c-hanging-comment-ender-p nil
		+	indent-tabs-mode
		+	(not
		+	(and (string-match "/\\(PEAR\\\|pear\\)/" (buffer-file-name))
		+	(string-match "\.php$" (buffer-file-name))))))</pre>
		+
		+	Here are Vim rules for the same thing:
		+
		+	<pre>set expandtab
		+	set shiftwidth=4
		+	set softtabstop=4
		+	set tabstop=4</pre>
		+
		+	It is recommended to keep lines at approximately 75-85 characters long for better code readability.
		+
		+
		+	=== Control Structures ===
		+
		+	These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:
		+
		+	<pre><?php
		+	if ((condition1) \|\| (condition2)) {
		+	action1;
		+	} elseif ((condition3) && (condition4)) {
		+	action2;
		+	} else {
		+	defaultaction;
		+	}
		+	?></pre>
		+
		+	Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.
		+
		+	You are strongly encouraged to always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.
		+
		+	For switch statements:
		+
		+	<pre><?php
		+	switch (condition) {
		+	case 1:
		+	action1;
		+	break;
		+
		+	case 2:
		+	action2;
		+	break;
		+
		+	default:
		+	defaultaction;
		+	break;
		+	}
		+	?></pre>
		+
		+
		+	=== Function Calls ===
		+
		+	Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:
		+
		+	<pre><?php
		+	$var = foo($bar, $baz, $quux);
		+	?></pre>
		+
		+	As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:
		+
		+	<pre><?php
		+	$short = foo($bar);
		+	$long_variable = foo($baz);
		+	?></pre>
		+
		+
		+	=== Function Definitions ===
		+
		+	Function declarations follow the "BSD/Allman style":
		+
		+	<pre><?php
		+	function fooFunction($arg1, $arg2 = '')
		+	{
		+	if (condition) {
		+	statement;
		+	}
		+	return $val;
		+	}
		+	?></pre>
		+
		+	Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:
		+
		+	<pre><?php
		+	function connect(&$dsn, $persistent = false)
		+	{
		+	if (is_array($dsn)) {
		+	$dsninfo = &$dsn;
		+	} else {
		+	$dsninfo = DB::parseDSN($dsn);
		+	}
		+
		+	if (!$dsninfo \|\| !$dsninfo['phptype']) {
		+	return $this->raiseError();
		+	}
		+
		+	return true;
		+	}
		+	?></pre>
		+
		+
		+	=== Comments ===
		+
		+	Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks (''to be defined'' - [[User:Dirk\|Dirk]]} sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. Further information can be found on the phpDocumentor website.
		+
		+	Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.
		+
		+	C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.
		+
		+
		+	=== Including Code ===
		+
		+	Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with <code>require_once</code> will not be included again by <code>include_once</code>.
		+
		+	:'''Note:''' <code>include_once</code> and <code>require_once</code> are statements, not functions. Parentheses should not surround the subject filename.
		+
		+
		+	=== PHP Code Tags ===
		+
		+	Always use <code><?php ?></code> to delimit PHP code, not the <code><? ?></code> shorthand. This is required for PEAR compliance and is also the most portable way to include PHP code on differing operating systems and setups.
		+
		+
		+	=== File Formats ===
		+
		+	All scripts contributed to Geeklog must:
		+
		+	* Be stored as ASCII text
		+	* Use ISO-8859-1 character encoding (''Exception:'' language files)
		+	* Be Unix formatted<br>"Unix formatted" means two things:
		+	*# Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
		+	*# There should be one line feed after the closing PHP tag (<code>?></code>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.

@@ Line 31: / Line 31: @@
 Specifically, we are adopting the following PEAR conventions:
-* Indenting and Line Length
+* Indenting and Line Length [http://pear.php.net/manual/en/standards.php#standards.indenting (1)]
-* Control Structures
+* Control Structures [http://pear.php.net/manual/en/standards.control.php (2)]
-* Function Calls
+* Function Calls [http://pear.php.net/manual/en/standards.funcalls.php (3)]
-* Function Definitions
+* Function Definitions [http://pear.php.net/manual/en/standards.funcdef.php (4)]
-* Comments
+* Comments [http://pear.php.net/manual/en/standards.comments.php (5)]
-* Including Code
+* Including Code [http://pear.php.net/manual/en/standards.including.php (6)]
-* PHP Code Tags
+* PHP Code Tags [http://pear.php.net/manual/en/standards.tags.php (7)]
-* File Formats
+* File Formats [http://pear.php.net/manual/en/standards.file.php (8)]
-To be defined: "Header Comment Blocks" [http://pear.php.net/manual/en/standards.header.php (1)]. It may also make sense to adopt "E_STRICT-compatible code" [http://pear.php.net/manual/en/standards.e_strict.php (2)] but that may be difficult to achieve in some contexts. It should certainly become a long-term goal, though.
+To be defined: "Header Comment Blocks" [http://pear.php.net/manual/en/standards.header.php (9)]. It may also make sense to adopt "E_STRICT-compatible code" [http://pear.php.net/manual/en/standards.e_strict.php (10)] but that may be difficult to achieve in some contexts. It should certainly become a long-term goal, though.

@@ Line 1: / Line 1: @@
-== Coding Guidelines for Geeklog 1.4. ==
+= Coding Guidelines for Geeklog 1.4. =
-Geeklog 1.x never had any formal coding guidelines so you may find different styles in different places. This is an attempt to pull things together again slightly and help avoid further diversification ...
+Geeklog 1.x never had any formal coding guidelines so you may find different styles in different places. '''As of March 2007, all new code in Geeklog will have to follow the PEAR coding standards''' (see below for details).
-'''Why have Code Conventions?'''
 To quote from the [[Coding_StandardsG2|Geeklog 2 Coding Standards]]:
@@ Line 14: / Line 15: @@
-=== Code Layout ===
+== Why pick the PEAR coding standard? ==
-==== The two styles compared ====
+* It's widely used and accepted in the PHP community.
-<pre>    if(( $arg1 == 42 ) || ( $arg2 > 23 ))
+= PEAR Coding Standards =
-i.e. opening curly brackets go on their own line and there's a space after opening and before closing round brackets.
+The following is about the actual source code formatting, i.e. how to place braces and what and how much whitespace to use. The PEAR naming conventions (file names, function names, etc.) are too different from Geeklog's and are not part of Geeklog's Coding Guidelines.
-The style used elsewhere is more compact:
+Specifically, we are adopting the following PEAR conventions:
-<pre>    if (($arg1 == 42) || ($arg2 > 23)) {
+* Indenting and Line Length
-        $result = call_function ($arg1, $arg2);
+* Control Structures
-    } else {
+* Function Calls
-        $result = call_other_function ($arg1, $arg2);
+* Function Definitions
-    }</pre>
+* Comments
-i.e. the opening curly bracket goes at the end of the line that opens the code block (exception: function headers). There is no space after opening or before closing round brackets (the space between the function name and the brackets is optional).
+To be defined: "Header Comment Blocks" [http://pear.php.net/manual/en/standards.header.php (1)]. It may also make sense to adopt "E_STRICT-compatible code" [http://pear.php.net/manual/en/standards.e_strict.php (2)] but that may be difficult to achieve in some contexts. It should certainly become a long-term goal, though.

@@ Line 18: / Line 18: @@
 ==== Indentation ====
-As it says on the top of nearly all of Geeklog' .php files: ''Reminder: always indent with 4 spaces (no tabs).''
+As it says on the top of nearly all of Geeklog's .php files: ''Reminder: always indent with 4 spaces (no tabs).''
 ==== Comments ====
@@ Line 34: / Line 34: @@
 // is also a multi-line comment</pre>
-Function header should always be preceeded by a PHPDoc-like function description using the /** ... */ style (note the extra '*'):
+Function headers should always be preceeded by a PHPDoc-like function description using the /** ... */ style (note the extra '*'):
 <pre>/**
@@ Line 85: / Line 85: @@
      }</pre>
-i.e. the opening curly bracket goes at the end of the line that opens the code block (exception: function headers). There is no space after open or before closing round brackets (the space between the function name and the brackets is optional).
+i.e. the opening curly bracket goes at the end of the line that opens the code block (exception: function headers). There is no space after opening or before closing round brackets (the space between the function name and the brackets is optional).