Difference between revisions of "Coding Guidelines"

From GeeklogWiki
Jump to: navigation, search
(New Coding Guidelines, mostly following the PEAR Coding Standards)
m (added link to Commit Messages page)
 
(7 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. '''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).
  
  
 
== Why have Code Conventions? ==
 
== Why have Code Conventions? ==
 
To quote from the [[Coding_StandardsG2|Geeklog 2 Coding Standards]]:
 
  
 
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.
Line 31: Line 29:
 
Specifically, we are adopting the following PEAR conventions:
 
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 (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. 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.
 +
 
 +
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]]
 +
 
  
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.
+
[[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