Coding Best Practices

This page describes the commenting and code style used in the PhpGedView project.

Freedom of Expression

Coding is an art form and code style is often unique to the developer who wrote it. In general PhpGedView developers are allowed the freedom to write code in the style that is most comfortable for them. This allows developers to be more productive and happier while working on the project.

While freedom of expression and artistic style are allowed to flourish, it is still expected that developers will be able to read each other's code. So there are some loose guidelines that should fit into most developer's coding practices.

Indentation

Indentation is a simple coding convention that all developers probably already do and is probably the #1 thing which improves the readability of code.

All code blocks should be indented. Here are some examples: Basic if statement block:

if ($var == true) {
    print "line1";
    print "line2";
}

Basic function definition with inner loop block:

function myfunct() {
    for($i=0; $i<100; $i++) {
        print $i;
    }
}

Example of wrapping long lines:

if (!userCanEdit(getUserName()) || !$ALLOW_EDIT_GEDCOM)
        print $pgv_lang['access_denied'];
    

There is plenty of religious debate on the net over whether tabs or spaces or better are better for indentation. The PhpGedView project does not officially promote tabs or spaces, but you will find that most code is written with tabs.

When in Rome...

If you are making minor changes to existing code, then for readabilty you should try to match the existing coding style.

If you are coding new blocks of code, you may use your preferred coding style.

Commenting

We are more strict about API level commenting just because most of the tools for generating API documentation require it. In PhpGedView you should use PHPDoc/JavaDoc style commenting for all functions, classes, and methods.

An example of PHPDoc/JavaDoc looks like this:

/**
 * Short description of my class or function
 * 
 * Long description of my class or function
 * which may span multiple lines
 * @param int $integer    description of this integer parameter
 * @param string $string  description of this string paramter
 * @return string         description of what this function returns
 */
function myFunc($integer, $string) {
    for($i=0; $i<$integer; $i++) {
        $string .= $string;
    }
    return $string;
}

Code Optimisation

There are lots of things that can affect the efficiency of the PHP code. Some knowledge about how the PHP interpreter handles different representations of the same code and how similar functions behave similarly but work somewhat differently. Here are some pointers on what should be best practices for writing optimised PHP code.

Single Vs Double Quotes and Comma Vs Concatenation

Anything in double quotes is first parsed by the PHP interpreter to check for any variables that need to be interpolate. Whereas strings with single quotes are simply parsed by the interpreter as a single "block". Therefore you should ALWAYS use single quotes unless you explicitly require variable interpolation.

Examples of such situations:

Less Efficient	More Efficient	Explanation
echo "print this string";	echo 'print this string';	single quoted string doesn't need to be parsed for variables
echo 'print this string with ' . $some_variable;	echo 'print this string with ', $variable;	using a list rather than concatenation means that a temporary variable holding the concatenation isn't required
print 'print this string';	echo 'print this string';	print() takes only one argument so requires concatenation (with temporary variables for the concatenation) and has a return value. For simple printing of info, use echo unless you need to use print() within an expression such as $b ? print "true" : print "false";
echo "A $string with $lots of $variables";	echo "A {$string} with {$lots} of {$variables}";	If you have to use lots of variable interpolation inside double quotes (e.g. because otherwise it would look horribly messy), put curly braces around the variables - it helps the PHP interpreter find them more efficiently
$array["key"]	$array['key']	single quoted string doesn't need to be parsed for variables
$array["$key"]	$array[$key]	no string interpolation is needed in this case so double quotes simply force the PHP interpreter to do additional checks for variables within the quoted string

Links

Single Vs Double Quotes and Comma Vs Concatenation

http://blog.libssh2.org/index.php?/archives/28-How-long-is-a-piece-of-string.html

http://www.brianhaveri.com/?id=34

http://www.weberdev.com/get_example-3750.html

Echo Vs Print

http://www.faqts.com/knowledge_base/view.phtml/aid/1/fid/40

Optimisation Guidance

http://lists.netfielders.de/pipermail/typo3-dev/2003-September/000493.html