Introduction
The Bug Genie uses a specific coding style / coding standard which we urge you to follow. By following the same coding style everywhere, we ensure that the code is easy to read and understand, as well as debug, fix and maintain. If you want your module included in the official module repository on thebuggenie.com, you must ensure that it follows the coding style specified in this document.There are several common coding standards in use in all kinds of projects - we're not promoting one over the other. However, we've chosen a certain coding style for The Bug Genie to make our lives easier. This standard may differ in some areas from other coding standards such as zend framework, symfony and pear so please look through this document carefully.
General formatting rules
Encoding
As long as is possible, all files should be UTF-8 encoded.PHP tags
<?php
?>Indentation, line length and line breaks
The Bug Genie does not have a maximum line length policy. Keep it readable.When indenting your code, use one tab per indentation level. Don't expand tabs to spaces as this may cause the indentation to appear out-of-style in other editors.
Line breaks follow the Zend Framework convention - here is the description taken from their coding style document:
Line termination follows the Unix text file convention. Lines must end with a single linefeed (LF) character. Linefeed characters are represented as ordinal 10, or hexadecimal 0x0A. Note: Do not use carriage returns (CR) as is the convention in Apple OS's (0x0D) or the carriage return - linefeed combination (CRLF) as is standard for the Windows OS (0x0D, 0x0A).
Naming conventions
Filenames
Files must follow the conventions set elsewhere in the documentation - that is:- All classes must use the correctly cased classname, suffixed by .class.php: MyClassname.class.php
- Interfaces, abstract- and exception classes follow the same convention as above
- Only exception here is the actions.class.php and actioncomponents.class.php files
- Templates must be named according to their format, and their corresponding action name: index.html.php
Classes
Classes must not contain underscores or be all lowercased, and must follow the CamelCasing style:/**
* Example "My module" class
*/
class MyModule
{
}Class methods
Class methods must use the same CamelCasing style for the naming, and should also be prefixed with words such as can, is, get or set where appliccable. This applies for both static and non-static methods:/**
* Example "My module" class
*/
class MyModule
{
static public function getInstance()
{
}
public function getName()
{
}
public function setName()
{
}
public function canAccessRestrictedArea51()
{
}
}On a related note, all class methods must declare their visibility: public, protected or private. Using the PHP4-compatible var declaration is not allowed.
Functions
Contrary to class methods and static function, regular functions must be named all lowercase, with words separated with an underscore. This makes it easy to visually distinguish between them, and maintains a good level of readability in templates./**
* Example "My function" function
*/
function my_function()
{
}Variables
Variables should be as descriptive as possible while still stay readable. They must also follow the same rules as naming regular functions, that is: only lowercase letters, spaced with underscores:// wrong, also not very readable
$myvar1 = "something";
// right
$current_user = $user;Constants
Constants must be all UPPERCASE, spaced with underscores. No exceptions. This goes for both class constants and regular constants:// wrong
define("MYFANCYCONST", 1);
// right
define("MY_FANCY_CONSTANT", 2);
/**
* Example "My module" class
*/
class MyModule
{
// right
const MY_REGULAR_CONSTANT = 3;
// one-word constants can't really be spaced, so this is correct
const AGE = 72;
}Spacing and newlines
Newlines
The Bug Genie uses a verbose coding style. That means using spacing and newlines to increase readability. We do not follow the "less is more" motto. More is more. New lines should appear before all opening and closing braces, in all types of statements, declarations and conditions: Functions:/**
* Example "My function" function
*/
function my_function()
{
}Classes:
/**
* Example "My module" class
*/
class MyModule
{
static public function getInstance()
{
}
public function getName()
{
}
}Spacing
Use spacing before opening paranthesis on all control statements (e.g.: if, while, for ....) and also after each comma, conditional test or semicolon in a parameter list. Do not use spacing after opening parenthesis or before closing parenthesis: Control statements:if ($something == true)
{
}
for ($cc = 1; $cc <= 10; $cc++)
{
}
switch ($something)
{
case 1:
break;
case 2:
break;
default:
break;
}Use spacing between concatenated elements to improve readability:
$my_string = "My age is " . $age . " and my height is " . $height;Use variable substitution when it makes sense, such as in the above example:
// These two styles are ok
$my_string = "My age is $age and my height is $height";
$my_string = "My age is {$age} and my height is {$height}";
// Try not to use this style
$my_string = "My age is ${age} and my height is ${height}";C-style or BASIC-style
The Bug Genie uses two different styles for control statements, depending on whether it is inside or outside templates. Inside templates, the following style is used:<p> some html code here </p>
<?php if ($something): ?>
<p> something </p>
<?php endif; ?>
<ul>
<?php foreach ($array as $element): ?>'
<li> element </li>
<?php endforeach; ?>
</ul>This style is not used anywhere but in templates. Do not use this style inside functions, classes or anywhere else. Do use this style in templates. The only exception here is switch statements which must contain the entire opening and closing switch block:
<p> some html code here </p>
<?php
switch ($something)
{
case 1:
?> something 1 <?php
break;
case 2:
?> something 2 <?php
break;
}
?>
