Development Standards: PHP
We might as well start this series off at the bottom and work our way up. So, let’s start with PHP – it’s not the base of our stack, but it’s the first element that heavily requires some coding standards in place.
As I said in the intro, this series will be about how I do things, although of course it’s all heavily based on what I’ve seen and used elsewhere, and what I’ve known to work. Given this, I’ll also talk about the toolkits and frameworks I use: Code Igniter on the server side and jQuery on the client side. I also use YUI Reset and Fonts at the top of most or all CSS.
Although it’s just as important I won’t talk about sticking to some semblance of good MVC practice when using Code Igniter. There’s plenty of that out there.
Why have development standards?
Possibly the main reason is that one person working on the code can understand what another has done. If I look at anyone else’s code and it’s formatted in a way that obfuscates its meaning, I’m possibly going to miss something key.
Looking forward, if something isn’t correctly formatted, fixing a bug is going to be that much easier if it’s easily readable. This applies whether it was written by a different person or not.
PHP tags
In view files, the short opening tag <? as opposed to <?php is encouraged, as is its logical next step <?=$var?>. Reducing clutter in view files, where front-end developers or even designers may work, is worthwhile.
Indentation
All code – HTML, CSS, Javascript, PHP – should be indented correctly. All indents should be 1 single tab. I prefer to view that in my editor – whether it’s TextMate or Vim – as four columns. How you view it in your editor is a personal preference, as long as the file itself uses 1 tab.
Line endings
All line endings should be a single \n – i.e. Unix-style. In addition, add no trailing spaces to lines, and remove any that sneak in due to slack editing.
Control Structures
Including if, for, while, switch, etc:
INCORRECT in various ways
if(condition1){
//action1
}
elseif(condition2){
//action2
}else{
//action3
}
CORRECT
if (condition1) {
//action1
} elseif (condition2) {
//action2
} else {
//action3
}
Another example:
for ($i = 0; $i < 10; $i++) {
...
}
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.
A switch block:
switch (condition) {
case 'one':
action1;
break;
case 'two':
action2;
break;
default:
action3;
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:
INCORRECT
$var=foo($bar,$baz,$quux);
CORRECT
$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.
Function Declarations
We usually try to put the arguments with default values at the end of the list:
function fooBar($var1, $var2 = '') {
if (condition) {
statement;
}
return $value;
}
Arrays
Always use spaces:
$array = array('val1', 'val2', 'val3');
If the array is even remotely large, break it into separate lines:
$array = array(
'key1' => 123,
'key2' => 'foo',
'key3' => getValue('bar'),
);
Notice the extra comma after the last element – this means we can rearrange the elements or add a new element with worrying about commas between elements. (This only works with PHP.)
Comments
Single line comments go like this:
// Check the value of foo.
$bar = isset($foo) ? $foo : '';
Multi-line, “C-style” comments:
/*
Check the value of foo.
This is to prevent errors.
*/
$bar = isset($foo) ? $foo : '';
Notice that the comment characters are on their own lines.
Includes
For unconditional inclusion, use require_once 'includefile.php';
For conditional inclusion, use include_once 'includefile.php';
Note: require_once and include_once are statements (or language constructs) not functions, so no parenthesis is required, or desired.
Metadata
Every applicable file should use an Id keyword:
<?php
// $Id$
which gets expanded by Subversion to
<?php
// $Id: codingstandards 758 2008-05-15 01:35:58Z dom $
Naming conventions
Functions and Methods
All names should start lowercase and use interCaps/camelCase
function getFooBar() {
...
}
No underscores in the middle of function names, please:
INCORRECT
function get_foo_bar() {
...
}
Private methods should start with an underscore:
function _getFooBar() {
...
}
Classes
Classes follow the same method as methods ;) except start with uppercase.
class FooBar {
function FooBar() {
...
}
}
Constants
Constants should be all UPPERCASE, except internally-provided ones like true, false, null;
File Format
All files should be unix format – I do not want to see any \r\n…