Coding Standards
To facilitate consistency and 'maintainability', Osprey developers have agreed upon these coding standards. Many of these standards closely resemble the coding standards for Pear developers, with a few minor changes.
- Naming Conventions
- Indenting and Line Length
- Control Structures
- Function Calls
- Function Defintions
- Comments
- Including Code
- PHP Code Tags
Naming conventions
Classes
Use camel case. For example:
class !FooBar
{
...
}
Do not use successive upper case letters for acronyms - i.e. SQLParser would be incorrect...use SqlParser? instead. Use nouns for class names.
For function and method defintions
Use lower case for the first letter and upper case for every other letter representing a new word. Only use letters - no underscores. For example:
function setFooBar ( )
{
...
}
Like class definitions, do not use successive upper case letters for acronyms. Use verbs for class names.
For variables
Capitalize all letters for new constants, file pointers, and static variables. All other variables should only use lower case letters. Use the underscore as a word delimiter - i.e. $number_of_apples.
Indenting and Line Length
Use tab indention, no spaces.
Control structures
Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls. Also, the opening 'squiggly' bracket should be on the same line as the expression itself, one space after the closing parenthesis.
if ( !($INFILE = fopen($file, 'r')) ) {
print("Problems opening $file.\n");
exit();
} else {
print("Success.");
}
Always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.
Function calls
Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon.
$var = foo($arg1, $arg2, $arg3);
As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:
$var = foo($arg1, $arg2, $arg3); $arrPosition = count($arr);
Since Osprey uses an MVC framework and most of the printing is done via Smarty Templating, you shouldn't need to use a print statement. However, should you need to use one, be sure to use print instead of echo, and parenthesis around the string argument.
Function Definitions
Function declarations follow the "one true brace" convention:
<?php
function isValidMessage ( $string )
{
$limit = 4;
if ( strlen($string) > $limit) ) {
return(true);
}
return(false);
}
?>
Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:
<?php
function connect ( &$dsn, $persistent = false)
{
if ( is_array($dsn) ) {
$dsninfo =& $dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if ( !$dsninfo || !$dsninfo['phptype'] ) {
return $this->raiseError();
}
return true;
}
?>
Comments
Osprey uses PHPDoc. Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found at the PHPDoc web site
Including code
Anywhere you are unconditionally including a class file, use require_once(). Anywhere you are conditionally including a class file (for example, factory methods), use include_once(). Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once() will not be included again by include_once().
PHP Code Tags
Use <?php ?> instead of the shorthand <? ?>.
