Hacking on Sitellite

Chapter 2: Coding Standards

The following standards have been put in place to ensure a high level of quality throughout the Sitellite codebase. You are not required to follow these for your own projects, however if you intend to contribute your changes back into the Sitellite core, then the code must meet these standards as part of our quality assurance review process.

Why have coding standards?

Code conventions are important to programmers for a number of reasons:

80% of the lifetime cost of a piece of software goes to maintenance.
Hardly any software is maintained for its whole life by the original author.
Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly. If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

Indentation and spacing

Space is always added between a function call and its braces, and any separate statements. For example:

<?php

// query the database for some info
$result = db_fetch ('select * from some_table');

// check for errors
if (! $result) {
	trigger_error (db_error ());
}

// loop through and display the results
foreach ($result as $item) {
	echo template_simple ('some_template.spt', $item);
}

// let's concatenate a string.  note the ample space.
$a = 'one' . 'two';

?>

Tabs are preferred to spaces, because although most editors can be set to generate a set number of spaces when the Tab key is hit, I find backspacing to be inconsistent, and I don't like hitting backspace 4 times in a row. Tabs help preserve our fingers. Tab stops should be set at the equivalent of 4 spaces in your editor.

Code must be indented properly, as shown in the examples throughout this document.

Just remember, more space is better than less, so adding blank lines between structures, declarations, and such is highly encouraged.

Braces

Braces are always required.

The initial brace is always kept at the end of the line that initiates its block, as opposed to being on its own on the line below. This is the case consistently across conditional and looping structures, functions, classes, and anywhere else curly braces are used.

Naming

Class, method, and property names use the camel-style naming convention, but global functions use underscores to separate words. For example:

<?php

class NewClass {
	var $someProperty;

	function propertySetter ($value) {
		$this->someProperty = $value;
	}
}

function some_function () {
	// ...
}

?>

For global functions, we maintain the PHP style of using underscores to separate words in function names. However for necessarily long names for classes, methods, and properties (which should be generally avoided anyway) we use the Java way: countActiveUsers.

Note that under no circumstances do we Ever Capitalize Every Word Of Our Code Like Some Companies Do (VB Anyone?). This would be grounds for flogging, but instead we let the carpel tunnel take care of you instead. ;)

Private properties and methods should start with a single underscore (not two, as that has special meaning in PHP and could cause strange behaviour and/or naming conflicts). For example, $someObject->_privateMethod ().

Constants are always upper-cased, with underscores separating words. A constant defined in a specific class or package should be prefixed with that class or package name. For example, the saf.Template.Simple package defines a constant named SIMPLE_TEMPLATE_DELIM_CURLY.

Commenting

Comments should be liberal. Code should be written in such a way that it is self-explanatory. For code that is not so obvious, comments are required. For classes, PhpDoc-style documentation is required. A note on comment content: Try not to document how a block of code does something, but rather document what it does.

Comments should use the C/C++ styles (/* */ and //), not the Perl/shell style (#). For example:

<?php

/**
 * This is a sample comment.
 *
 * @access public
 */
class Foo {
    /**
     * This is another sample.
     *
     * @access public
     */
    function bar ($asdf) {
        // This is an inline comment.
        echo $asdf;
    }
}

?>

PHP-Specific Issues

File names for PHP files should always end in .php, never .php3 or .php4. This is in the name of portability.

Full <?php open tags are absolutely required. This is fundamental to the portability of the software.

Platform-specific "tricks" (not that there are many in PHP) must be avoided unless absolutely necessary, in which case an Atticus Finch worthy argument must be made for them. This includes calling shell scripts that are only available on a Unix platform. This of course does not apply if your app is intended for a specific platform.

PHP extensions that are not available in a default PHP build must be avoided in the name of portability. This is a regretful thing, as there are some really useful non-default extensions available. For custom code, if the client's server environment will specifically support extra extensions, the use of such extensions is acceptable. This of course also does not apply to app writers, who have the choice of adding compatibility requirements (although we encourage app writers to try to meet the same level of compatibility as Sitellite itself.

Compatibility with a minimum PHP version must be maintained (usually two dot-releases behind the current stable release) in order to preserve portability. Major version number changes will be handled carefully as special cases.

Quality Assurance

All new code and bug fixes must be accompanied by proper documentation, which may often just be a verbose description in the CVS changelog.

phpt tests may be included as a separate file in saf/tests, which can be run as part of a centralized quality assurance process.

Miscellaneous

Files should always be saved with Unix line breaks, regardless of the platform.

example.com is the recommended URL to use for examples and documentation, as per RFC 2606. yourWebSite.com is also acceptable.

References

Chapter 3: Parts of Sitellite »

Comments

You must be logged in and registered for this course to comment.

Username:
Password:
	Forgot your password?

Member Login