{{TOC}}
= 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 [http://framework.zend.com zend framework], [http://symfony-project.org symfony] and [http://pear.php.net 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 ==
<source lang="php">
<?php

?>
</source>
PHP tags should always start with the full '''<?php''' tag - short (open) tags are not allowed. For files that contains only php (classes, function libraries, etc.) the closing php tag ('''?>''') is not allowed. This prevents accidental run-on whitespace at the end of the file which may break The Bug Genie.

== 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:
<source lang="php">
/**
 * Example "My module" class
 */
class MyModule
{
}
</source>

=== 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:
<source lang="php">
/**
 * Example "My module" class
 */
class MyModule
{
    static public function getInstance()
    {
    }

    public function getName()
    {
    }

    public function setName()
    {
    }

    public function canAccessRestrictedArea51()
    {
    }
}
</source>

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.
<source lang="php">
/**
 * Example "My function" function
 */
function my_function()
{
}
</source>

=== 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:
<source lang="php">
// wrong, also not very readable
$myvar1 = "something";

// right
$current_user = $user;
</source>

=== Constants ===
Constants must be all UPPERCASE, spaced with underscores. No exceptions. This goes for both class constants and regular constants:
<source lang="php">
// 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;
}
</source>

== 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:'''
<source lang="php">
/**
 * Example "My function" function
 */
function my_function()
{
}
</source>

'''Classes:'''
<source lang="php">
/**
 * Example "My module" class
 */
class MyModule
{
    static public function getInstance()
    {
    }

    public function getName()
    {
    }
}
</source>

=== 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:'''
<source lang="php">
if ($something == true)
{
}

for ($cc = 1; $cc <= 10; $cc++)
{
}

switch ($something)
{
    case 1:
        break;
    case 2:
        break;
    default:
        break;
}
</source>

Use spacing between concatenated elements to improve readability:
<source lang="php">
$my_string = "My age is " . $age . " and my height is " . $height;
</source>

Use variable substitution when it makes sense, such as in the above example:
<source lang="php">
// 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}";
</source>

== 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:
<source lang="php">
<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>
</source>

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:
<source lang="php">
<p> some html code here </p>
<?php

    switch ($something)
    {
        case 1:
            ?> something 1 <?php
            break;
        case 2:
            ?> something 2 <?php
            break;
    }

?>
</source>

[[Category:TheBugGenie:Development]]