Wiki : CodingStandards
Documentation Home :: Categories :: Index :: Recent Changes :: Comments :: Search :: Help :: Login/RegisterPostNuke Coding Standards
Indenting
Use an indent of 4 spaces, with no tabs. If you use Emacs to edit PostNuke code, you should set indent-tabs-mode to nil.
Here are vim example rules:
set expandtab set shiftwidth=4 set softtabstop=4 set tabstop=4
You can use the indent tool to properly indent your code. Try out the following options:
indent -nut -bap -br -ce -cli4 -ncs -ss -npcs -saf \
-sai -saw -nprs -bfda -psl -brs \
-lp -nbbo -hnl -i4 -ci4Control Structures
These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.
You are strongly encouraged to 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.
For switch statements:
switch (condition) {
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
break;
}
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
break;
}
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. Here's an example:
$var = foo($bar, $baz, $quux);
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:
$short = foo($bar);
$long_variable = foo($baz);
$long_variable = foo($baz);
Function Definitions
Function declarations follow the "one true brace" convention:
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}
{
if (condition) {
statement;
}
return $val;
}
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:
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;
}
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return true;
}
Comments
Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.de/∞
Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.
C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.
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().Note: include_once() and require_once() are statements, not functions. You don't need parentheses around the filename to be included.
PHP Code Tags
Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is required for PostNuke compliance and is also the most portable way to include PHP code on differing operating systems and setups.For files containing php code only the closing tag should be exluded to prevent any trailing whitespace from being treated as valid output.
Header Comment Blocks
All source code files in the core PostNuke distribution should contain the following comment block as the header:
/**
* PostNuke Application Framework
*
* @copyright (c) 2001, PostNuke Development Team
* @link http://www.postnuke.com
* @version $Id: $
* @license GNU/GPL - http://www.gnu.org/copyleft/gpl.html
* @package <package>
* @subpackage <sub package>
*/
* PostNuke Application Framework
*
* @copyright (c) 2001, PostNuke Development Team
* @link http://www.postnuke.com
* @version $Id: $
* @license GNU/GPL - http://www.gnu.org/copyleft/gpl.html
* @package <package>
* @subpackage <sub package>
*/
Files not in the core PostNuke repository should have a similar block stating the copyright, the license, and the authors.
Example URLs
Use "example.com" for all example URLs, per RFC 2606.Naming Conventions
Generally speaking, the names of classes, functions and variables should always be descriptive enough to easily tell the reader of the code what they are used for.CategoryReference
CategoryKnowledgeBase
CategoryDeveloperDocs
|
