Coding Style Guide

Observium uses procedural PHP to maintain code readability and accessability. Object Oriented coding isn't permitted except where it's required to interface with external libraries.

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 never between brackets. Preferably using single quotes ' unless double quotes " allows strings to be unescaped.
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.

Commenting

There isn't a one-size-fits-all answer to the ideal comment-to-code ratio, as it depends man factors. However, some general guidelines can help you strike a balance between too few and too many comments in your PHP code:

Aim for clarity: The primary goal of comments is to clarify the code and make it more readable. If your code is self-explanatory, you may not need to add many comments. However, if there are complex algorithms or obscure logic, adding comments will improve the code's maintainability and readability.
Follow the DRY (Don't Repeat Yourself) principle: Avoid writing comments that merely restate what the code is doing. Instead, focus on providing context, explaining the rationale behind the code, or outlining any assumptions.
Document functions and classes: Use PHPDoc-style comments to document functions, classes, and their properties. This practice will provide useful information to other developers and can be used to generate API documentation automatically.
Inline comments: Use inline comments sparingly, and only when they provide valuable information that isn't immediately apparent from the code itself.
Keep comments up-to-date: As you modify your code, ensure that you update the comments accordingly. Outdated comments can be more harmful than no comments at all.
Use meaningful variable and function names: Well-named variables and functions can reduce the need for comments, as they convey the purpose of the code more effectively.

While there's no strict rule on the comment-to-code ratio, a good rule of thumb is to aim for around 10-20% comments, depending on the code's complexity. Remember, the quality of the comments matters more than their quantity. The goal is to strike a balance between readability and maintainability, without overloading the code with unnecessary comments.