The Bug Genie
The Bug Genie
star_faded.png
Please log in to subscribe to updates for this article
The Bug Genie:Development:Coding Style
Last updated at Mon Feb 21 08:01, by System

Introduction  ⇑ top

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  ⇑ top

Encoding  ⇑ top

As long as is possible, all files should be UTF-8 encoded.

PHP tags  ⇑ top

<?php

?>
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  ⇑ top

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  ⇑ top

Filenames  ⇑ top

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  ⇑ top

Classes must not contain underscores or be all lowercased, and must follow the Camel Casing style:
/**
 * Example "My module" class
 */
class MyModule
{
}


Class methods  ⇑ top

Class methods must use the same Camel Casing 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  ⇑ top

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  ⇑ top

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  ⇑ top

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  ⇑ top

Newlines  ⇑ top

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  ⇑ top

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  ⇑ top

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;
    }

?>



Article attachments

There are no file attached to this article

Article comments (0)

There are no comments