glFusion Wiki

Site Tools


glfusion:development:codingstandards

glFusion Coding Standards

All new code in glFusion will have to follow the following 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, etc.)

Coding Guidelines

Indenting and Line Length

Use an indent of 4 spaces, with no tabs. This helps to avoid problems with diffs, patches, SVN history and annotations.

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. 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 “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 the most portable way to include PHP code on differing operating systems and setups.

File Formats

All scripts contributed to glFusion 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.

– Original page from http://wiki.geeklog.net/Coding_Guidelines

glfusion/development/codingstandards.txt · Last modified: 2017/04/12 21:11 (external edit)

Page Tools