Wandervogel Sub-System

Version 1.1

Last Release: 08.06.2008

Website Updated: 08.06.2008

Programming Style

This section describes the coding principles used in the Wandervogel sub system.

The Wandervogel system is written in a coding style that is mash-up of the Java programming language and C++.

Basic

Below are examples of some basic coding practices Wandervogel implements to make code easier to read while also eliminating possible errors that may creep in:

<\?php

// Instead of
$myClass->getObject()->doFunction();

// For clarity, one could also do the following. While this method may seem to create
// more code it simplifies the logic and avoids the possibility of null pointers
// (when getObject() doesn't return an object, but null)
$obj = $myClass->getObject();
if (!is_null($obj))
{
    $obj->doFunction();
}

// Or, as in the first example
try
{
    $myClass->getObject()->doFunction();
}
catch (Exception $e)
{
    print $e->exception; // Can't remember the actual string that displays the Exception
}

// Consider (Makes code more clear)
$obj = $myClass->getObject();

// Catches possible error where NULL pointer is returned
if (!is_null($obj))
{
    $obj->doFunction();
}

Spacing

Tab length is approximately 4 spaces (\s). Tabs are not to be considered (\t).

Function & Variable Names

Function naming conventions are similar to C conventions. This is a clear distinction between method calls.

All lowercase with hyphen separating different words:

 foo_bar();

Variable naming conventions are similar to Java conventions with a few differences:

First letter is always lowercase

 $fooBar;

Acronyms placed in the name will have only its first letter capitalized while the others are lowercase

 $myXmlResponse;

Acronyms beginning a variable name are to be all lower case

 $xmlString;

Variable names that contain an integer value have similar conventions as normal variable and function names. One thing to note is that the first letter after the number is lowercase

 $ref1firstName;

Constants

Constant variables must be in uppercase. Each word in the variable is separated by an underscore.

define('MY_CONSTANT', 1);

Classes & methods

Each word in a class name should have their first letter capitalized. The opening bracket must begin on a new line:

class Customer
{
    // Class code
}

Names that include acronyms can maintain their capitalization:

class XMLReport
{
    // Class code
}

Class methods follow the same criteria as functions and variables.

Control Structures

There should be one blank line above and below a control structure. Exceptions to this rule are for comments, which should have a blank line above them. All control structures must have the first bracket on a new line flush with the first letter of the control structure name.

Code within a control structure should be indented by one tab length of 4 spaces.

Conventions include:

if...statement

$test = null;

// comment here
if ($myVar === true)
{
    // code here
}

Long if...statement

(Indentation of the conditions is optional)

if (
    $foo == true &&
    $bar == true &&
    $baz == true &&
    $foobar == true
)
{
    // code here
}

/* OR */

if (
    ($foo == true || $bar == true) &&
    ($baz == true || $foobar == true)
)
{
    // code here
}

while...statement

while (true)
{
    // code here
}

switch...statement Switch statements require that a return character is contained after each ''break''. This clearly delimits each case condition one from the other and provides a clear break (''pardon the pun'') between the conditions.

switch ($type)
{
    case 'NEEDY':
        // Code
        break;
                    ← Notice space between break and next case condition
    case 'GREEDY':
        // Code
        break;

    default;
} // switch ← Optional

for...statement

for ($i = 0; $i < LIMIT; ++$i)
{
    // code here
}

Database

Valid table names:
customers, applications, hart_reports, etc.

Invalid:
Customers, HART_Reports

The Wandervogel system has built-in inflection utilities that will change any table name to its singular representation. Given a database table customers a PHP class will be generated with a class name of customer.

Depending on the coding style selected for your project, Wandervogel will automatically convert variables given a table name or table column name and create class files that adhere to the selected coding style. For instance, consider the project table in the Installing section. The PHP class name and member variables will be generated to look like the following if the coding style selected is Java:

<\?php

class Project { // Class name camelized. Opening bracket on same line as class name
    public $id;
    public $dateCreated;    // date_created column has been camelized to dateCreated
    public $name;
}

?>