Coding Standards

Simian Coding Standards

Why Have Coding Standards?
Indentation and Spacing
Braces
Naming
Commenting
PHP-Specific Issues
Quality Assurance
Miscellaneous
References

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 someNewClass {
	var $someProperty;

	function somePropertySetter ($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, PhpDocumentor documentation is required before calling a package 1.0 or stable. A note on comment content: Never document *how* a block of code does something, document *what* it does.

- Comments should use the C and/or C++ styles (/* */ and //), not the Perl/shell style (#).

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.

- PhpUnit tests should be included as a separate file in saf/tests, which can be run as part of a centralized quality assurance process using saf/tests/index.php.

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.