There is no such thing as a perfect standard; coding style is largely a matter of personal preference. Much more valuable than choosing “the perfect style” is having a consistent style across all your code.You shouldn’t be too hasty to change a consistent style you don’t particularly like.
Code Formatting and Layout
When you’re using tabs to indent code, you need to make a consistent decision about whether the tabs are hard or soft. Hard tabs are regular tabs. Soft tabs are not really tabs at all; each soft tab is actually represented by a certain number of regular spaces.The benefit of using soft tabs is that they always appear the same, regardless of the editor’s tab-spacing setting.
In general, try to break up any line that is longer than 80 characters because 80 characters is the width of a standard Unix terminal window and is a reasonable width for printing to hard copy in a readable font.
Control Flow Structures
The usage of braches even with single line statement is highly recommended to keep the code maintainable. Consider something like this:
if (is_null($age))
$age = 20;
We a new line is added to the same control statement, it’d possible to forgot adding brace and then think that it works with the condition.
Consistently using braces
There are couple of brace placement types:
- BSD style
if ($condition)
{
// statement
}
- GNU style
if ($condition) { // statement }
- K&R style
if ($condition) { // statement }
The K&R style is named for Kernighan and Ritchie, who wrote their uber-classic The C Programming Language by using this style.
Discussing brace styles is almost like discussing religion. Which brace style you choose is ultimately unimportant; just making a choice and sticking with it is important.
You should not use a while loop where a for or foreach loop will do.
Avoiding deeply nested loops
Code snippet like this one
$fp = fopen(“file”, “r”); if ($fp) { $line = fgets($fp); if($line !== false) { // Do work } else { // nothing in the file } else { // File not found }
Can be simplified to something like that which would be more readable
$fp = fopen(“file”, “r”); if (!$fp) { // File not found } $line = fgets($fp); if($line == false) { // no lines } // Do work
Naming Symbols
You can break PHP variables into three categories that can follow different naming rules:
- Truly global: intended to be used in global scope
- Long-lived: can be referred at any scope or referenced through large blocks of code.
- Temporary: used in small sections of code to hold temporary information. The constants and truly global variables are defined with all uppercase letters.
Long-lived variables should have concise but descriptive names.
Temporary variable names should be short and concise.
There are two ways of naming multiword names:
- Studly caps or camel caps
$myVariable = 'value';
- Underscore as break:
$my_variable = 'value';
The second would be better because these reasons:
- Keeping consistent separation scheme in place for global and temporary variables. Because if thee camel caps used then a global variable can be something like $MYGLOBAL
- Nonnative English speakers will find looking up your variable names in a dictionary easier if the words are explicitly broken with underscores.
Naming consistency
Variables that are used for similar purposes should have similar names. Code that looks like this demonstrates a troubling degree of schizophrenia:
$num_elements = count($elements); … $objects_cnt = count($objects);
If one naming scheme is selected, then there is less need to scan through the code to make sure you are using the right variable name. For example, following $num_ naming for all count variables would be consistent.
Matching Variable Names to Schema Names
Variable names that are associated with database records should always have matching names. Here is an example of good variable naming style; the variable names all match the database column names exactly.
Avoiding Confusing Code
One of the principal beauties of PHP is that it allows for embedding of HTML in PHP and PHP in HTML. You should take advantage of this ability and get rid of using echo to constructs HTML as possible.
Documentation
Documentation can be broken down into two major categories:
- Inline comments that explain the logic flow of the code, aimed principally at people modifying, enhancing, or debugging the code.
- API documentation for users who want to use the function or class without reading the code itself.
API documentation
Documenting an API for external users is different from documenting code inline. In API documentation, the goal is to ensure that developers don’t have to look at the code at all to understand how it is to be used. API documentation is essential for PHP libraries that are shipped as part of a product and is extremely useful for documenting libraries that are internal to an engineering team as well.
These are the basic goals of API documentation:
- It should provide an introduction to the package or library so that end users can quickly decide whether it is relevant to their tasks.
- It should provide a complete listing of all public classes and functions, and it should describe both input and output parameters.
- It should provide a tutorial or usage examples to demonstrate explicitly how the code should be used.
In addition, it is often useful to provide the following to end users:
- Documentation of protected methods
- Examples of how to extend a class to add functionality