Coding Style Guide#

Indenting and spacing#

  • 2 spaces. No tabs!

Blocks#

  • { and } are on separate lines, unless the content is only one statement.
  • for/while/if/foreach are always surrounded by {}, even if they are only executing one statement.
  • Ternary operators should be avoided, and full if() {} blocks are preferred.

Formatting#

  • One space between for/if/foreach/while and the following opening bracket.
  • Empty line between the global line and the rest of the code in a function.
  • Empty line between the final return statement and the rest of the code in a function.
  • Parameters to echo always between brackets, even if PHP does not require it.
  • No trailing spaces on any line!

One statement per line#

Never combine statements on one line.

INCORRECT:

$foo = 'this'; $bar = 'that'; $bat = str_replace($foo, $bar, $bag);

CORRECT:

$foo = 'this';
$bar = 'that';
$bat = str_replace($foo, $bar, $bag);

Variable naming#

Variables should contain only lowercase letters, use underscore separators, and be reasonably named to indicate their purpose and contents. Very short, non-word variables should only be used as iterators in for() loops.

INCORRECT:

$j = 'foo';     // single letter variables should only be used in for() loops
$Str            // contains uppercase letters
$bufferedText       // uses CamelCasing, and could be shortened without losing semantic meaning
$groupid        // multiple words, needs underscore separator
$name_of_last_city_used // too long

CORRECT:

for ($j = 0; $j < 10; $j++)
$str
$buffer
$group_id
$last_city

Function naming#

Function names should contain only lowercase letters, use underscore separators and be reasonbly named to indicate their purpose and contents. Very short, very long or camelCase names shouldn't be used.

All functions should be given a valid docblock with a description of the function and its variables, at the very minimum it should be given a "FIXME" docblock.

INCORRECT:

function fileproperties()       // not descriptive and needs underscore separator
function fileProperties()       // not descriptive and uses CamelCase
function getfileproperties()        // Better!  But still missing underscore separator
function getFileProperties()        // uses CamelCase
function get_the_file_properties_from_the_file()    // wordy

CORRECT:

function get_file_properties()  // descriptive, underscore separator, and all lowercase letters

Variable types#

Arrays#

Do not use short array sintax, we still retain compatibility with older php versions.

INCORRECT:

$groups_index = [];
$id = dbFetchCell($qry, [$group_name]);

CORRECT:

$groups_index = array();
$id = dbFetchCell($qry, array($group_name));

Booleans#

Always use uppercase boolean literals.

INCORRECT:

$foo = True;
$foo = false;

CORRECT:

$foo = TRUE;
$foo = FALSE;

Object Oriented Programming#

We strongly discourage the use of OOP. For a project such as ours, we need to keep the code easy to read with a low barrier to entry. It's unlikely that any contributions using OOP will be committed to the codebase.

There can be exceptions made when using PEAR code, or other external libraries, but in general, stay away from OOP.

Optimization#

  • If you're going to be doing a lot of checking if entities exist within the database during a module, cache the contents of the table in an array instead.
  • Use internal caching functions as much as possible.

PHP tags#

  • No short tags, always use the full <?php instead of <? and <?php echo($foo); ?> instead of <?= $foo ?>.

The PHP closing tag on a PHP document ?> is optional to the PHP parser. However, if used, any whitespace following the closing tag, whether introduced by the developer, user, or an FTP application, can cause unwanted output, PHP errors, or if the latter are suppressed, blank pages. For this reason, all PHP files should OMIT the closing PHP tag, and instead use a comment block to mark the end of file and it's location relative to the application root. This allows you to still identify a file as being complete and not truncated.

INCORRECT:

  <?php

  echo "Here's my code!";

  ?>

CORRECT:

  <?php

  echo "Here's my code!";

  /* End of file myfile.inc.php */

Shebang#

  • For command-line executable scripts, use /usr/bin/env instead of a direct path to the php interpreter binary.