coding_guidelines

Code guidelines related to PHP code.

Inherited from Codeigniter, we don't use the '?>' closing tag to avoid any errors or blank pages when the error_reporting is set to hide the messages. Also, certain ftp clients tend to add weird characters and replace the starting or ending whitespace.

Correct usage:

<?php
$dummy_variable = 'dummy text';
//END OF FILE

Class names should have the first letter uppercase and not use the CamelCase naming style. We like underscores as we find them easier to follow. Also, the naming should be descriptive if possible.

Method names should follow the same guide except for the first letter which should be lowercase.

class Form_validation {
 
	function form_validation ()
	{
 
	}
 
}

Variables inherit the same properties from classes and methods. 1 letter variables are never used except in loops.

Comments should be added at the beginning of every file (copyrights, version, author, year etc.), at the beginning of every new class (definition, package, version) and at the beginning of every function/method.

If the code gets complicated and hard to follow by other team members, inline documentation is also recommended.

All of our constants are uppercase with underscores separating multiple words.

All three of them should be written in uppercase as well.

function dummy ()
{
	return TRUE;
}

Never use HTML in PHP unless forced or if it wouldn't make sense to load a template file for a small piece of code.

Use smarty templates to build your presentation.

A space follows and precedes all logical operators.

if ( 1 == 1 || 1 !== TRUE && ! empty ( $dummy_array )

No white space should precede the opening php tag or the end of your file.

PHP4.3+, MySQL4.1+

Always add a prefix to classes and file names that are using common words such as email, upload, rss, xml etc.

Use tabs for whitespace. Some of us use tabs of 4, others of 8 and this is adjustable in the majority of IDE's. We are used to follow the code based on the indentation. Using spaces will not make possible this customization so it's quite important for us yes.

Except for classes, braces are always on a new line.

function foo ( $bar ) 
{
 
}
 
foreach ( $arr as $key => $val )
{
 
} 
 
if ( $foo == $bar )
{
 
}
else
{
 
}

We use spaces before and after all parenthesis, brackets and punctuations, however, this is not so important.

Any text that is inserted should use language variables in your module's lang file to allow localization.

Lang ( 'lang_key' );

Instead of:

echo "some string";

Always use full PHP opening tags:

<?php echo $variable; ?>

Use a new line for every statement you add:

$var = 1;
$var_a = 2;
$var_b = 3;
 
//INSTEAD OF
 
$var = 1; $var_a = 2; //etc.

Whenever makes sense and possible, try to use default values for function parameters to avoid any errors from mistaken calls.

function do_this ( $var = FALSE, $mem_id = 1 )

Should inherit the same properties from classes and methods.

Your queries should always be escaped using the 'qstr' function available in functions_helper.php

• always try to avoid using queries in loops and work with result_array (or an array of your own) instead to build your results.
• too many queries or extremely slow queries won't be accepted.
• use JOIN and SUBSELECT whenever possible to cut down the number of queries per page.
• use indexes in your tables to speed up the queries.
• always capitalize commands and keywords: SELECT, INSERT, REPLACE, UPDATE, DELETE, AND, OR, WHERE etc.
• use LIMIT for queries whenever possible.
• when doing a JOIN, the joined table columns should come first in the ON's clauses.
• always use the table prefix (DBPREFIX) constant in front of the table names

SELECT * FROM ' . DBPREFIX . 'table_name ...

• follow the same standards as PHP for operators (spaces before and after punctuation etc.)
• use multiple line queries: they are more readable, and easier to modify with modifications.

• don't prefix every column in a table with a certain prefix - use table aliases instead (otherwise you only make the names longer, forcibly.)
• instead of table id which is always uppercase and called 'ID', all other columns should start with lowercase letters, and use either camelCase or some_underscores.
• if a column has no reason to ever be NULL, specify NOT NULL (this saves space in the table data.)
• provide default values whenever possible, and assume they may be used in other modifications, etc.
• never use a default and auto_increment together.
• comment queries outside the query, not inside (we wouldn't want the comment piped to the server through memory!)

Always try to build a secure application. Always verify parameters by type as much as possible. Always escape your queries. Don't leave anything unchecked.