Difference between revisions of "Coding Guidelines"

From GeeklogWiki
Jump to: navigation, search
(A (late) first attempt for some Geeklog 1.4 coding and style guidlines)
 
m (added link to Commit Messages page)
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Coding Guidelines for Geeklog 1.4. ==
+
= Coding Guidelines for Geeklog =
  
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 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).
  
'''Why have Code Conventions?'''
 
  
To quote from the [[Coding_StandardsG2|Geeklog 2 Coding Standards]]:
+
== Why have Code Conventions? ==
  
 
Code conventions are important to programmers for a number of reasons:
 
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.
 
* 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.
 
* 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.
  
  
=== Code Layout ===
+
== Why pick the PEAR coding standard? ==
  
==== Indentation ====
+
Using the [http://pear.php.net/manual/en/standards.php PEAR coding standard] makes sense for several reasons:
  
As it says on the top of nearly all of Geeklog' .php files: ''Reminder: always indent with 4 spaces (no tabs).''
+
* It's widely used and accepted in the PHP community.
 +
* It's short and clear.
 +
* Geeklog already uses some PEAR packages.
 +
* Most of the code in Geeklog (apart from that based on lib-common.php) already uses a formatting style that's similar to the PEAR conventions.
  
==== Comments ====
 
  
Single-line comments should always use the // comments separator. Multi-line comments can consist of either consecutive lines all using the single-line comment separator or they can use /* ... */
+
= PEAR Coding Standards =
  
 +
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.
  
<pre>// this is a single-line comment
+
Specifically, we are adopting the following PEAR conventions:
  
/* while this
+
* Indenting and Line Length [http://pear.php.net/manual/en/standards.php#standards.indenting (1)]
* is a multi-line comment
+
* Control Structures [http://pear.php.net/manual/en/standards.control.php (2)]
*/
+
* Function Calls [http://pear.php.net/manual/en/standards.funcalls.php (3)]
 +
* Function Definitions [http://pear.php.net/manual/en/standards.funcdef.php (4)]
 +
* Comments [http://pear.php.net/manual/en/standards.comments.php (5)]
 +
* Including Code [http://pear.php.net/manual/en/standards.including.php (6)]
 +
* PHP Code Tags [http://pear.php.net/manual/en/standards.tags.php (7)]
 +
* File Formats [http://pear.php.net/manual/en/standards.file.php (8)]
  
// but this
+
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.
// 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 '*'):
 
  
<pre>/**
+
== Coding Guidelines ==
* This function does some cool stuff
 
*
 
* @param  string  $entry  the entry's text
 
* @param  int      $value  the corresponding value, max. range 0..42
 
* @return  bool              returns true for valid entries
 
*
 
*/</pre>
 
  
 +
=== Indenting and Line Length ===
  
==== Main ====
+
Use an indent of 4 spaces, with '''no tabs'''. This helps to avoid problems with diffs, patches, CVS history and annotations.
  
PHP files that are not meant to be included should have a "main" section near the ''end'' of the file that is to be clearly marked as such, e.g. with a comment like this:
+
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>// MAIN</pre>
+
<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>
  
The implementation of all functions local to this .php file should go above the main section.
+
Here are Vim rules for the same thing:
  
 +
<pre>set expandtab
 +
set shiftwidth=4
 +
set softtabstop=4
 +
set tabstop=4</pre>
  
=== Brackets and Spacing ===
+
It is recommended to keep lines at approximately 75-85 characters long for better code readability.
  
Over time, two main styles for placing brackets and spaces have developed: The one used in lib-common.php, that has since been begun to be picked up by some (but not all) the system/lib-*.php files and the style used in almost all the other files.
 
  
When adding or editing code, make sure to pick up the style of the surrounding code. There is nothing more irritating than trying to read some piece of code that switches back and forth between various coding styles.
+
=== Control Structures ===
  
 +
These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:
  
==== The two styles compared ====
+
<pre><?php
 +
if ((condition1) || (condition2)) {
 +
    action1;
 +
} elseif ((condition3) && (condition4)) {
 +
    action2;
 +
} else {
 +
    defaultaction;
 +
}
 +
?></pre>
  
The style used in lib-common.php is more "spacious" and looks something like this:
+
Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.
  
<pre>   if(( $arg1 == 42 ) || ( $arg2 > 23 ))
+
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.
     {
+
 
         $result = call_function( $arg1, $arg2 );
+
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();
 
     }
 
     }
    else
 
    {
 
        $result = call_other_function( $arg1, $arg2 );
 
    }</pre>
 
  
i.e. opening curly brackets go on their own line and there's a space after opening and before closing round brackets.
+
    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. 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 (<code>/* */</code>) and standard C++ comments (<code>//</code>) are both fine. Use of Perl/shell style comments (<code>#</code>) 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.
  
The style used elsewhere is more compact:
+
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.
 +
 
 +
 
 +
= Also See =
 +
 
 +
* [[Best Practices]]
 +
* [[Commit Messages]]
  
<pre>    if (($arg1 == 42) || ($arg2 > 23)) {
 
        $result = call_function ($arg1, $arg2);
 
    } else {
 
        $result = call_other_function ($arg1, $arg2);
 
    }</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).
+
[[Category:Development]]

Latest revision as of 13:09, 13 March 2010

Coding Guidelines for Geeklog

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).


Why have Code Conventions?

Code conventions are important to programmers for a number of reasons:

  • 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.


Why pick the PEAR coding standard?

Using the PEAR coding standard makes sense for several reasons:

  • It's widely used and accepted in the PHP community.
  • It's short and clear.
  • Geeklog already uses some PEAR packages.
  • Most of the code in Geeklog (apart from that based on lib-common.php) already uses a formatting style that's similar to the PEAR conventions.


PEAR Coding Standards

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.

Specifically, we are adopting the following PEAR conventions:

  • Indenting and Line Length (1)
  • Control Structures (2)
  • Function Calls (3)
  • Function Definitions (4)
  • Comments (5)
  • Including Code (6)
  • PHP Code Tags (7)
  • File Formats (8)

To be defined: "Header Comment Blocks" (9). It may also make sense to adopt "E_STRICT-compatible code" (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):

(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))))))

Here are Vim rules for the same thing:

set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4

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:

<?php
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
?>

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:

<?php
switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;
}
?>


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:

<?php
$var = foo($bar, $baz, $quux);
?>

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:

<?php
$short         = foo($bar);
$long_variable = foo($baz);
?>


Function Definitions

Function declarations follow the "BSD/Allman style":

<?php
function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}
?>

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:

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


Comments

Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks (to be defined - 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 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 require_once. Anywhere you are conditionally including a class file (for example, factory methods), use include_once. 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 require_once will not be included again by include_once.

Note: include_once and require_once are statements, not functions. Parentheses should not surround the subject filename.


PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> 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
    "Unix formatted" means two things:
    1. 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.
    2. There should be one line feed after the closing PHP tag (?>). 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 configure Mercurial such that it won't allow you to commit files with the "wrong" line endings.


Also See