Coding Guidelines and Conventions
History Key
- New content
Removed content
Recent Versions
Choose two versions to compare, or click the link to view it.
Indentation
Use soft-tabs instead of hard-tabs, ie. do not use spaces when indenting code. Spaces can be used to indent 3/4, 1/2 and 1/4 of a tab, but not as primary means of indenting code. The tabs makes indenting easier, because there is no risk of starting an indent block on the 7th space instead of the 8th. You also save 3 chars for each tab (vs 4 spaces).
Use 4 spaces as tab length.
Constants
Booleans
False and true should be written in lowercase, this because of two reasons: the uppercase variants take too much attention and they are also aliases for the lowercase variants.
Use syntax highlighting which displays boolean values in a distinguished color and/or in italic/bold instead.
Other
All other constants should be uppercase only, NO CamelCasedConstants – use UNDERSCORED_TEXT instead. Descriptive names is a must!
Operators
All operators should be preceded and succeeded with a single space (even when just inside the parenthesis):
if( ! empty($foo))
OR should be used instead of ||
&& should be used instead of AND
Lists
In all types of lists (eg. arrays and parameter lists) should the separating commas ALWAYS be followed by a space.
Use the RegEx at the end to fix this.
Control Structures
Brackets
Brackets are placed on the line following a control structure, with the same amount of indentation as the line with the control structure.
Bracketless control structures should be avoided, because you’ll never know when you need to add something extra in the associated block.
Spaces
It should not be any spaces inside the parentheses following the control structure, neither should it be any space after the name of the control structure.
// wrong:
if ( somecondition )
{
echo “foobar”;
}
// correct:
if(somecondition)
{
echo “foobar”;
}
The reason is that the spaces call too much attention to the if and somecondition.
Files
PHP ending tag
The ending tag should be skipped in PHP-only files, to avoid “Cannot modify header information – headers already sent” errors.
To clarify that the file ends, add this at the end:
/* End of file myfile.php /
/ Location: ./project/path/to/file */
Encoding
Always use UTF-8 encoding with unix style linebreaks (LF, not CRLF)
One file per class
This makes it easier to locate classes and makes it easier to work on them. Excepting classes with limited length (<30 lines) which is closely related with the other one(s) in the same file, same goes for utility functions (if you have a few utility classes/functions, consider putting them in a separate file).
Name the file after the class, with the exception that the first char is uppercase and the rest lowercase.
Functions and Methods
Naming
Use underscored_names instead of camelCasedNames, this to make them easier to read.
Documentation
Use PHPdoc-style doc-comments for all functions and methods. Add a short line describing what it does, then the types of accepted parameters and the expected output type.
Ordering
Group them after what they do, not their name (IDEs and editors have good search functions nowadays).
Function/Method calls
Do not use spaces around or just inside the parentheses.
func(‘arg’, ‘arg2’);
// not:
func ( ‘arg’, ‘arg2’ );
// or
func( ‘arg’,‘arg2’ );
Default values
Use them where it is possible, and do not use default values for a required parameter.
Separators
Use an empty line + separator line (indented) + empty line to separate methods from each other.
separator line:
// -————————————————————————————————-
Classes
Properties
Should be placed in the top of the class and documented with a PHP doc comment which describes what it contains and the variable type. Separate properties with an empty line.
Separate the properties section from the method section with empty line + separator line (indented) + empty line.
Constructor and magic methods
They should be placed directly after the properties, to make them easy to find.
__construct() or class_name()?
If you are coding for PHP 5, use __construct() as the constructor name.
Public methods
Should be placed after the constructor/magic methods.
Private/Protected methods
They should be placed last, with the utility methods at the end.
SQL
Always write SQL keywords in uppercase, the same with built-in database functions (like COUNT and CONCAT).
Always escape foreign data.
Error messages
Use useful error messages, so even a poorly experienced user can understand it.
Useful Regular expressions
A few useful regular expressions for code.
Ignore the surrounding citation marks, they define the beginning/end of the search/replace.
Add spaces after commas
Search: “,(\S)” Replace: “, $1”
Remove trailing whitespace
Search: “(?<=^|\S)[\t ]+$” Replace: “”