Nucleus Code Layout / Guidelines

Tabs vs Spaces

Use tabs, not spaces, for indenting code. Make sure that when you save the file, it's saving tabs and not spaces. This way, the code can be displayed the way each person likes it, without breaking the layout of the actual files.

The practice of using tabs within a line to align the right side of assignments should be avoided.

Linefeeds

Ensure that your editor is saving files in the UNIX (LF) line ending format. This means that lines are terminated with a newline, not with Windows Line endings (CR/LF combo) as they are on Win32 or Classic Mac (CR) Line endings. Any decent editor should be able to do this, but it might not always be the default setting.

File Encoding

All text files must be encoded with UTF-8 without byte order marks.

Variables

Variables should be named using lowercase, and words should be separated with an underscore. For example, $current_user is correct, but $currentuser and $currentUser are not.

Names should be descriptive, but concise. No need for huge sentences for variable names, but typing an extra couple of characters is always better than wondering what exactly a certain variable is for.

Functions

Functions should be named using lowercase, and words should be separated with an underscore. They should include a verb somewhere if at all possible. For example, get_user_data() and validate_form_data(). Make it as obvious as possible what the function does from its name, while remaining reasonably concise.

Classes

Classes should be named using “UpperCamelCase.” For example:

class DatabaseConnection extends PDO

Class methods and properties should use “lowerCamelCase”:

public $lastStatement;

Constants

Constants should be named using all uppercase, and words should be separated with an underscore. For example, USER_ACTIVE_LEVEL is correct, but USERACTIVELEVEL or user_active_level are not.

This includes pre-defined PHP constants like TRUE, FALSE, and NULL.

Loop Indices

The only situation where a one-character variable name is allowed is when it's the index for some looping construct. Unless you already have a counting variable with a meaningful name, use $i as the variable for the outermost loop, then go onto $j for the next nested loop, etc. However, do not use the variable $l (lowercase “L”) in any of your code as it looks too much like the number “one.”

for ( $i = 0; $i < $outer_size; $i++ )
{
   for ( $j = 0; $j < $inner_size; $j++ )
   {
      foo($i, $j);
   }
}

Always include the braces

Braces should always be included when writing code using if, for, while, etc. blocks. There are no exceptions to this rule, even if the braces could be omitted. Leaving out braces makes code harder to maintain in the future and can also cause bugs that are very difficult to track down.

These are all incorrect

if (condition) do_stuff();
 
if (condition)
	do_stuff();
 
while (condition)
	do_stuff();
 
for ($i = 0; $i < size; $i++)
	do_stuff($i);

These are all correct

if ( condition )
{
	do_stuff();
}
 
while ( condition )
{
	do_stuff();
}
 
for ( $i = 0; $i < size; $i++ )
{
	do_stuff();
}

Where to put the braces

Braces should always be placed on a line on their own. Again, there are no exceptions to this rule. Opening and closing braces should both align to the same column as the control statement or function they belong to. For example:

if ( condition )
{
	while ( condition2 )
	{
		...
	}
}
else
{
	...
}
 
for ( $i = 0; $i < $size; $i++ )
{
	...
}
 
while ( condition )
{
	...
}
 
function do_stuff()
{
	...
}

Spaces

Put a space on both sides of operators.

Incorrect

$sum=$variable1+$variable2;

Correct

$sum = $variable1 + $variable2;

The exception is unary operators, which should not have a space between the operator and variable.

Incorrect

$a ++;
if ( ! $variable ) ...

Correct

$a++;
if ( !$variable ) ...

The concatenation operator (.) should have a space on both sides. For example:

$variable = 'Hello ' . $name;

Commas should have one space after, but none before. For example:

foo($variable1, $variable2, $variable3);

Semi-colons should not have spaces on either side when at the end of a line. If inline, a semi-colon should have one space after.

Incorrect

foo($variable1) ;
for ( $i = 1;$i < 10;$i++ ) ...

Correct

foo($variable1);
for ( $i = 1; $i < 10; $i++ ) ...

Functions should have no spaces between the name, opening parenthesis, and first argument. There should be no space between the last argument and the closing parenthesis. This applies to function declarations as well as function calls.

Incorrect

function foo ( $variable1, $variable2, $variable3 );
foo ( $variable1, $variable2, $variable3 );

Correct

function foo($variable1, $variable2, $variable3);
foo($variable1, $variable2, $variable3);

Control structures such as if, for, while, etc. should have one space on both sides of the opening parenthesis and one space before the closing parenthesis. This is to more easily differentiate between control structures and function calls.

Incorrect

if ($condition1)
{
	...
}

Correct

if ( $condition1 )
{
	...
}

However, individual conditions nested within a control structure should not have a space between their conditions and parentheses.

Incorrect

if ( ( $variable1 > 1 ) && ( $variable1 < 10 ) )
{
	...
}

Correct

if ( ($variable1 > 1) && ($variable1 < 10) )
{
	...
}

In these examples, each pair shows the incorrect way followed by the correct way:

$i=0;
$i = 0;
 
if($i<7) ...
if ( $i < 7 ) ...
 
if(( $i<7 )&&( $j>8 )) ...
if ( ($i < 7) && ($j > 8) ) ...
 
do_stuff( $i,'foo',$b );
do_stuff($i, 'foo', $b);
 
for($i=0; $i<$size; $i++) ...
for ( $i = 0; $i < $size; $i++ ) ...
 
$i=($j<$size)?0:1;
$i = ( $j < $size ) ? 0 : 1;

Operator precedence

Always make operator precedence obvious by using parentheses in an equation so you know what it does. Be careful to not overuse this, as it may diminish the readability, e.g. do not enclose single expressions. Examples:

result is not readily apparent

$bool = ( $i < 7 && $j > 8 || $k == 4 );

this gives a better idea of what's going on

$bool = ( ($i < 7) && (($j < 8) || ($k == 4)) );

But this one is even better, because it is easier on the eye but the intention is preserved

$bool = ( $i < 7 && ($j < 8 || $k == 4) );

Quoting strings

There are two different ways to quote strings in PHP — either with single quotes or with double quotes. The main difference is that the parser does variable interpolation in double-quoted strings, but not in single quoted strings. Because of this, you should always use single quotes unless you specifically need variable interpolation to be done on that string. This way, we can save the parser the trouble of parsing a bunch of strings where no interpolation needs to be done.

Also, if you are using a string variable as part of a function call, you do not need to enclose that variable in quotes. Again, this will just make unnecessary work for the parser. Note, however, that nearly all of the escape sequences that exist for double-quoted strings will not work with single-quoted strings. Be careful, and feel free to break this guideline if it's making your code easier to read, examples:

incorrect

$str = "This is a really long string with no variables for the parser to find.";
 
do_stuff("$str");

correct

$str = 'This is a really long string with no variables for the parser to find.';
 
do_stuff($str);

Sometimes single quotes are just not right

$post_url = $root_path . 'posting.' . $php_ex . '?mode=' . $mode . '&start=' . $start;

Double quotes are sometimes needed to not overcroud the line with concatenations

$post_url = "{$root_path}posting.{$php_ex}?mode={$mode}&start={$start}";

Note: when using variables combined with strings in this manner, please wrap the variable in braces to help separate them visually from the strings.

Associative array keys

In PHP, it's permitted to use a literal string as a key to an associative array without quoting that string. We don't want to do this—the string should always be quoted to avoid confusion. Note that this is only when we're using a literal, not when we're using a variable. For example:

incorrect

$foo = $assoc_array[key];

correct

$foo = $assoc_array['key'];

incorrect

$foo = $assoc_array["$variable"];

correct

$foo = $assoc_array[$variable];

Always use the <?php open tag instead of the short open tag <?.

The ?> closing tag of a PHP file should be omitted.

Only use the brace syntax for control structures. Do not use the alternative syntax.

Be careful with double-equals comparison operators. Triple-equals is often more intuitive.

'foo' == 0 // is true
'000' == '0' // is true
'000' === '0' // is false

Use && and || logical operators instead of AND and OR.

Set error_reporting to E_ALL during development to catch all PHP warnings and notices.

Do not access the PHP superglobals $_GET, $_POST, etc. directly. Instead, use the Nucleus functions getVar(), postVar(), requestVar(), or serverVar().

SQL Queries

When writing SQL queries, capitialize all SQL keywords (SELECT, FROM, VALUES, AS etc.). Table field names should be in lowercase. Table and field names should be enclosed in backtick characters. When using WHERE clauses to return data corresponding to a set of conditions, enclose those conditions in parentheses in the same way you would for PHP control structures, e.g.

SELECT * FROM `users` WHERE ( (`registered` = 'y') AND ((`user_level` = 'administrator') OR (`user_level` = 'moderator')) )

Use phpDoc style comments to document code.

It's recommended to add a comment identifying the end of a control structure on the same line as the closing brace. This is helpful particularly with complicated, nested control structures. For example:

if ( $condition1 )
{
 
	if ( $condition2 )
	{
		...
	} // end if condition2
 
} // end if condition1

Avoid using /* */ comment blocks for one-line comments, # or '' should be used for one/two-line comments.