phpClick

Home	Credits	Demo	Documentation	Download	FAQ

Documentation > Coding Standards

Coding Standards

We established the standards below in order to keep ourselves sane and the code as readable as possible. While collaborating on the implementation we found that each one of us had a slightly different code formatting style which made the code ugly and often harder to follow. Here are the guidelines we agreed on... not unbreakable rules :)

Naming

Capitalization

Classes

Begin with a capital letter and then capitalize the beginning of each new word

Ex – ClassName

Variables

Begin with a lowercase letter indicating their type (see further below) and then capitalize the beginning of each new word

Ex – $tVariableName

Methods/Functions

Begin with a lowercase letter and then capitalize the beginning of each new word

Ex – methodsAndFunctions()

Constants

Use all capitals and separate words with underscores

Ex – CONSTANT_VALUE

Special Conventions

Do not use upper case abbreviations and acronyms

Do use – parseXml()
Do not use – parseXML()

Hungarian Notation for Variable Names

Add letters to indicate type followed by the name of the variable.

Type

Add the following letters after the scope letter to indicate the type:

a for array
b for Boolean
c for character
f for floating point
i for integer
o for object, handle, reference
s for string

Some Examples

A float for calculating an employee's federal tax deductions – $fFedTax
A variable string that holds a employee's first name – $sFirstName

Prefix Notation for Methods/Functions

Add a prefix to indicate the method's/function's purpose followed by the name of the method/function.

Prefixes

Add the following prefixes to indicate the method/function's purpose:

get for methods/functions that get and return a specific value
set for methods/functions that take and set a specific value
is for methods/functions that ask a question and expect a true or false answer

Some Examples

A function that gets a configuration setting – getNumResultsToDisplay()
A method that servers as a mutator for the employee class – setFirstName($sFirstName)
A method that checks if an employee is authenticated – isAuthenticated($sUsername, $sPassword)

Indentation

Indent 4 spaces; do not use tabs.
The first code within a PHP file is not indented

Spaces

Use spaces around keywords (if, for, else, etc), operators (==, !=, <, etc), and commas and semicolons.

Do use – if (a < b)
Do not use – if(a < b)
Do not use – if (a<b)

Line Length

Limit the length of lines to 80 characters.

Braces

Place the starting brace at the end of the line and indent the body as in the following example:

if ($condition) {
body . . .
}

Also always use braces even if they are technically optional as in the following example

if ($condition) {
echo 'condition is true';
}

Quotes

Use single quotes to reference the elements of an array and for strings.

Ex – $_SESSION['userId']
Ex – $sFirstName = 'Jonathan'

Use double quotes only when necessary

Ex – "You can insert \n or \t and so on."

Commas and Periods

Use commas for outputting multiple items in echo statements

Ex – echo $sFirstName," ",$sLastName;

Documentation

Documenting Classes, Methods, Functions

phpDocumentor (http://www.phpdoc.org/) generates documentation for php code in a fashion similar to Javadocs. Create a comment block before each class, method, or function. The first part of the block is a brief description that is terminated by either a period or a blank line. The second part is a long description that is also terminated by a blank line. The third part is composed of tags.

The following tag is required:

@return – what is returned by the function including type information (not a standard tag in phpDocumentor). @return should be followed by the type of the variable. It is an object its class should be given instead. Use keyword "void" if there is no return value.

The following tags are optional:

@author – the author's name
@param – specifies the purpose of a parameter; use this if the parameter's purpose is not clear from its name (not a standard tag in phpDocumentor). @param should be followed by the type of the variable. It is an object its class should be given instead. Use separate @param tags for each of the input parameters without writing the parameter name actually and the phpDocumenter will map them automatically
@link – either links to another class, method, or function or to a url

The following is an example comment block:

/**
* Finds all employees in a department
*
* Generates and executes a SQL query based on the
* department ID that is passed in as a parameter. The query
* searches a database to locate all employees in the department.
*
* @author Jonathan Howarth
* @return array   a recordset for successful queries or an integer error
*                 code for unsuccessful queries
*/
function doEmployeeLookupByDepartment($iDepartmentId) {
    . . .
}

Inline Documentation

Inline documentation should be placed on the line before the code to which it refers as illustrated in the following example:

// cycles through all employees in one department
for ($i = 0; $i < $result->numRows(); $i++) {
$aEmployee = $result->fetchRow(DB_FETCHMODE_ASSOC, $i);
echo $aEmployee['firstName'].$aEmployee['lastName'];
}

Notifications

Use the following words to provide additional comments to the code:

BUG: – a known bug, provide a description
KLUDGE: – a quick fix that should be improved upon in later versions; provide an explanation of how to do it better
TODO: – a reminder to finish a particular section of the code
Ex – // KLUDGE: Just a temporary measure to test the code...

HTML Conventions

Write all HTML tags in lower case.

<a href="www.vt.edu">Virginia Tech</a>

Use 2 spaces to indent tags.

Write an entire php page inside of one set of php tags. In other words, do not close the <?php . . . ?> tag to write HTML. Instead use the following echo command:

<?php
php code . . .
echo <<<END
    This uses the "here document" syntax to output multiple lines
    with $variable interpolation. Note that the here document terminator
    must appear on a line with just a semicolon no extra whitespace!
END;
php code . . .
?>

File Naming conventions

Begin with a lowercase letter and then capitalize the beginning of each new word
Ex - addComponent.inc.php unless the file contains exactly one class in which case the file name starts with a capital letter to match the name of the class, Ex - Application.inc.php
For PHP files that are included by other PHP files use ending .inc.php (all files that cannot be run by themselves)
all PHP files have the ending .php
all HTML files have the ending .html (not .htm) - however, it is recommended to name all files .php even if they do not (yet) contain PHP code

PHP escaping

always use full PHP start tag <?php instead of <? or <%

http://phpclick.sourceforge.net/
Last modified: September 13, 2004
You are visitor number 1 since Nov. 25, 2009.

web hosting kindly provided by