Dokeos 2.0 Coding Conventions

From Dokeos

Jump to: navigation, search

Coding conventions for Dokeos 2.0 are based on the PEAR coding conventions. PEAR is a thoroughly-tested framework for PHP code libraries and the standards define the complete set of things we might wonder how to do best. Adhering to widely-used standards allow people to work more efficiently by giving them the ability to read other people's code much faster (just as if they coded it themselves).

Contents

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.
  • It is recommended to keep lines at approximately 75-85 characters long for better code readability. Please also read Paul M. Jones' thoughts[1] on this subject

Control Structures

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

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

Class Definitions

Class declarations have their opening brace on a new line: 

<?php
class Foo_Bar
{

    //... code goes here

}
?>

Function Definitions

Function declarations follow the "K&R style": 

<?php
function foo_function($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. C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged. Please check the Pear Coding Conventions Comments page on this topic for examples and more details.

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. Dokeos 2.0 will more then likely use require_once most of the time

PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

Header Comment Blocks

All source code files shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Check the Pear Coding Conventions Header Comment Blocks page for an example.

Example URLs

Use example.com, example.org and example.net for all example URLs and email addresses.

Naming Conventions

Classes

Dokeos 2.0 deviates from the official PEAR guidelines on this. Classes should be given descriptive names. Avoid using abbreviations whenever possible. Class names should always begin with an uppercase letter. The class hierarchy is reflected by using uppercase for the first letter of each level. Examples of good class names are:

  • Translation
  • LearningObject
  • RepositoryDataManager

Class Variables and Methods

Dokeos 2.0 deviates from the official PEAR guidelines on this. Class variables (a.k.a properties) and methods should be named using lowercase only and using an underscore as a seperator. Never use uppercase characters in names of class variables and/or methods. Some examples (these would be "public" members):

  • $publication
  • $learning_object
  • run()
  • as_html()
  • retrieve_learning_object()

Constants

Constants should always be all-uppercase, with underscores to separate words. Some examples:

  • APPLICATION_NAME
  • LEARNING_OBJECT_ID

File Formats

All contributed scripts must:

  • Be stored as ASCII text
  • Use ISO-8859-1 character encoding
  • Be Unix formatted

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 (?>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.

E_STRICT-compatible code

All new code must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

More details on this part of the Coding Standards can be found in the corresponding PEPr proposal.

Remark: This is not a real priority, but it should be an end goal.

Error Handling Guidelines

Please read the detailed explenation on the Pear Error Handling Guidelines page.

Best practices

There are other things not covered by PEAR Coding Standards which are mostly subject of personal preference and not directly related to readability of the code. Things like "single quotes vs double quotes" are features of PHP itself to make programming easier and there are no reasons not use one way in preference to another. Such best practices are left solely on developer to decide. The only recommendation could be made to keep consistency within package and respect personal style of other developers.

Source

The Pear manual on coding standards, locate at [2]

Retrieved from "http://www.dokeos.com/wiki/index.php/Dokeos_2.0_Coding_Conventions"
Personal tools