Naming Conventions & Coding Standards in PHP.
- PHP Files
- Names should be short & descriptive (either in German or English).
- If the module is handling a DB table, then its name should be same as the table itself omitting ‘table_’.
- Templates
- Name of template should be identical to the name of the php module with change in extension to ‘.tpl’ or .html
- If there is more than one template, then use postfix like ‘_xyz” to the template name. Eg : ‘user_header.tpl’ & ‘user_position.tpl’ or .html
- Functions
- Function name should be in English.
- Only Lower case letters to be used.
- Should contain 2 parts
- Appropriate Verb ( Eg. get)
- Manipulated Object( Eg. Product )
- Eg : get_students() | get_ students _name()
- A short description about the output and input parameters should also accompany the function description.
- Classes
- Class Names
- Camel Case convention should be followed.
- Beginning letter should be in Caps
- Variable Names
- Local variables : All small letters with ‘_’ for separation.
- Local Methods : Camel Case with beginning letter in ‘Small Caps’.
- Variable Names inside PHP code/modules
- Use Lower Case Letters only
- Use ‘_’ for separation.
Coding & Documentation
1. A DocBlock / Documentation Block.
A basic DocBlock looks like this:
/**
*
**/
To document any function, place the DocBlock immediately before the function declaration.
A DocBlock contains three basic segments in this order:
· Short Description
· Long Description
o The Short Description starts on the first line, and can be terminated with a blank line or a period. A period inside a word (like example.com or 0.1 %) is ignored. If the Short Description would become more than three lines long, only the first line is taken. The Long Description continues for as many lines as desired and may contain html markup for display formatting. Here is a sample DocBlock with a Short and a Long Description:
§ Example :
/**
* return the date of Easter
*
* Using the formula from "Formulas that are way too complicated for anyone to
* ever understand except for me" by Irwin Nerdy, this function calculates the
* date of Easter given a date in the Ancient Mayan Calendar, if you can also
* guess the birthday of the author.
*/
· Tags
o Optionally, you may enclose all paragraphs in a tag.
o Be careful, if the first paragraph does not begin with , phpDocumentor will assume that the DocBlock is using the simple double line break to define paragraph breaks as in Example:
/**
* Short desc
*
* Long description first sentence starts here
* and continues on this line for a while
* finally concluding here at the end of
* this paragraph
* This text is completely ignored! it is not enclosed in p tags
* This is a new paragraph
*/
2. TAGS
/*
* Here are the tags:
*
* @abstract
* @access public or private
* @author author name
* @copyright name date
* @deprecated description
* @deprec alias for deprecated
* @example /path/to/example
* @exception Javadoc-compatible, use as needed
* @global type $globalvarname
or
* @global type description of global variable usage in a function
* @ignore
* @internal private information for advanced developers only
* @param type [$varname] description
* @return type description
* @link URL
* @name procpagealias
or
* @name $globalvaralias
* @magic phpdoc.de compatibility
* @package package name
* @see name of another element that can be documented,
* produces a link to it in the documentation
* @since a version or a date
* @static
* @staticvar type description of static variable usage in a function
* @subpackage sub package name, groupings inside of a project
* @throws Javadoc-compatible, use as needed
* @todo phpdoc.de compatibility
* @var type a data type for a class variable
* @version version
*/
3. Other Considerations
a. Usage of space
i. For enhancing readability, spaces should be used between each function name , command , commas and brackets
b. Prevent lines with excess length.
i. Code should be readable in editors with normal number of character ( 80 or 100 max). Horizontal scrolling should be avoided.
ii. Example
$sql = sprintf ("SELECT %s FROM %s WHERE %s='%s'",
$field_value,
$table,
$field_index,
$id
);
And not like this one:
$sql = sprintf ("SELECT %s FROM %s WHERE %s='%s'", field_value, $table,$field_index, $id);
c. Positioning Of Brackets
i. If Statement
If (“ “)
{
….
….
}
Else
{
…
…
}
ii. Switch Statement
Switch(“ “)
{
case 1 :
line 1;
line 2;
break;
case 2 :
line 3;
line 4;
break;
}
d. Documenting Rule
i. Do not comment on things which are obvious.
ii. As a matter of principle , the variable name should give away the meaning of the same eliminating unwanted documentation.
iii. Make clear why a certain action is taken. As shown in the example :
/**
* An unregistered customer calls up a product
**/
If (isset($_SESSION["user"])==false)
{
/**
* All unregistered caller gets a temporary customer ID. If he registered during his
* session, all statistical data is to be rewritten on to his correct ID.
**/
if (isset ($_SESSION["tmpStudentID "])==false)
{
....
....
}
}
e. Documentation of implementation details and background
i. Its recommended that the developer documents the background details which are taken up for granted.
/**
* We are using a timer of seconds, risking the problem of two customers using the
* same function at the same second, not to be identified.
**/
$time = time();
$ StudentrID = $time;
$_SESSION["tmpStudentID"]=$StudentrID;
