DokuWiki

It's better when it's simple

User Tools

Site Tools


Sidebar

Translations of this page?:

Learn about DokuWiki

Advanced Use

Corporate Use

Our Community


Follow us on Facebook, Twitter and other social networks.

devel:coding_style

Coding Style

There are currently no really strict rules in how the code should be formatted, but a few basic things should be attended to when adding code to DokuWiki.

Brackets and Indentations

You should indent your code by 4 spaces to mark logical blocks. Please do not use tabs. Much code still uses 2 spaces; you should stick to this or change the whole file to 4 spaces.

Opening brackets should start on the same line as the keyword, closing bracket should be aligned below the first letter of the starting keyword. E.g.:

if ($foo == "bar") {
    call_bar();
} elseif ($foo == "baz") {
    call_baz();
} else {
    call_other();
}

Line Endings

Lines should end with a single linefeed character (UNIX style). Please try to avoid trailing whitespace. Have a look at our page about Vim to see how to set up Vim to spot these easily.

Commenting

Each function and class should have a PHPDocumentor style comment, giving at least the function's purpose and its author. Parameter and return value descriptions are encouraged but only mandatory if they are not obvious. If you enhance an existing function just add another author line.

Example:

/**
 * Check for foo in bar
 *
 * Checks if there is a foo in bar
 *
 * @author   Joe Schmoe <joe@example.com>
 * @param    string $in your input
 * @return   bool       true if foo in bar
 *
 */
function is_foo($in) {
    ...
}

These comments are used for the autogenerated API Docs.

PHP Closing Tags

You should omit PHP's closing tags (?>) in all files to avoid premature output. This may sound strange but is actually mentioned in the PHP manual:

Note: The closing tag of a PHP block at the end of a file is optional, and in some cases omitting it is helpful when using include() or require(), so unwanted whitespace will not occur at the end of files, and you will still be able to add headers to the response later. It is also handy if you use output buffering, and would not like to see added unwanted whitespace at the end of the parts generated by the included files.

Checking for Coding Style Violations

The development Git checkout contains a coding standard setup for the use with PHP_CodeSniffer in _cs/DokuWiki.

Setup

To install PHP_CodeSniffer run the following in your shell.

  pear install PHP_CodeSniffer

Link the DokuWiki coding standard to the CodeSniffer directory. You may need to adjust the paths depending upon your operating system.

  ln -s /path/to/dokuwiki/_cs/DokuWiki /usr/share/pear/PHP/CodeSniffer/Standards/DokuWiki

Set DokuWiki to be the default standard.

  phpcs --config-set default_standard DokuWiki

Usage

You can use PHP_CodeSniffer to check a single file or an entire directory including subdirectories using the following commands.

  # Check a single file
  phpcs myfile.php
  
  # Check all files in a directory
  phpcs /path/to/directory
devel/coding_style.txt · Last modified: 2013/01/28 16:08 by 141.65.129.192