Introduction

As an Open-Source software, Batavi needs to be written following some coding guidelines and/or rules. It is the required condition, code can't be accepted when it doesn't comply to these guidelines.

Some of those guides may seem obvious, others less. For all, it is principally a good way to produce more readable, maintainable and portable code.

General coding rules

Paths

It is forbidden to use absolute paths in Batavi. Batavi may be relocated which should be possible with very minimal even none reconfiguration. Only exception will be configure.php which can contain absolute paths.

E_STRICT-compatible code

All new code that is suggested for inclusion into Batavi must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_STRICT.

PHP

Coding Style

Developers should use the following coding standards. When in doubt use the PEAR coding standards. Developers should respect the [BSD KNF|http://en.wikipedia.org/wiki/Indent_style#BSD_KNF_style] coding style like Batavi currently uses.

Indent

Developers should respect the indentation conventions when writing PHP code in Batavi: 2 spaces indentations are default, the use of tabs for indentation is prohibited, use space instead (select the appropriate preferences in your favorite code editor if needed).

Additionally developers should consider following rule. As displayed below, there should be one space on either side of an equals sign used to assign the return value of a function to a variable (or assigning values within hash arrays, etc.). In the case of a block of related assignments, more spaces must be inserted to promote readability:

$short		= foo($bar);
$long_variable	= foo($baz);
$short		= foo($bar);
$long_variable	= foo($baz);
$short		= foo($bar);
$long_variable	= foo($baz);
$short		= foo($bar);
$long_variable	= foo($baz);
$short		= foo($bar);
$long_variable	= foo($baz);
$short		= foo($bar);
$long_variable	= foo($baz);
$short		= foo($bar);
$long_variable	= foo($baz);

Control structures

Control statements should have one space between the control keyword and opening parenthesis.
It is mandatory to use curly braces even when they are optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

This is correct:

if (condition) {   ...   }

Use of parenthesis and equals sign

When parentheses are put into another set of parentheses, do not use spaces between them. In contrary, when the equals sign, or "=" is written, you have to put spaces next to them.

This is correct:

if ($btv_Database->isError()) {
  $error = true;
}

This is not correct:

if ( $btv_Database->isError() ) {
  $error=true;
}

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.

This is correct:

$var = foo($bar, $baz, $quux);

Function declarations

Function declarations follow the "The One True Brace Style" convention. This means that the beginning brace starts at the same line as the function declaration.

This is correct:

function foo($bar) {

This is incorrect:

function foo($bar)
{

Class Modifiers

Modifiers keywords (public, protected, private) are mandatory in class members and methods definitions. It is recommended to use private for most members and properties; if uncertain use the private keyword. Use public only for methods that needs to be accessible from outside the class.

If classes are being extended or redeclared, it is generally better to use protected instead of private since most methods. Then only use private for members/properties you do not want to be redeclared.

PHP Code Tags

Always use

<?php ?>

to delimit PHP code, not the
<? ?>
shorthand.

Naming Conventions

Classes

Classes should be given descriptive names that should always begin with "btv_" following with an upper case letter for each new word. Avoid using abbreviations.

This is correct:

 public class btv_Database()

And this is correct:

public class btv_TemplateBox() {

This is incorrect

public class btv_Template_Box() {

And this is incorrect:

public class btv_Templatebox() {

Functions and Methods

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). Function and method names should always start with a lower case letter.
This is correct:

public function handleKeymapTool()

Functions and methods names should always describe actions. Developers must declare the access modifiers (public, private, protected) for each function or method. Private methods should always start with '_'.

Variables

Variables should be given descriptive names that should always be fully lower case written. Avoid using abbreviations. Each word is separated by an underscore (_).

Query variables

Query variables should be named in lower case, starting with a capital Q and given a descriptive variable name.

Example:

$Qcategories = $btv_Database->query(

Box variables

No variable should be named to the box anymore.

This is correct:

title;

This is incorrect:

box_login_title;

Variable names shall be short and descriptive.

This is correct:

customer.name, product.name;

This is incorrect:

account.customer.address.name, products.product_name;

All fieldnames shall be used from the DB table fieldname. If this is not correct or descriptive then this should be changed.

General variable name setup.

product information:
```
[%$product.<fieldname>%]
```

customer information:

[%$customer.<fieldname>%]
[%$customer.address.<fieldname>%]

order information:
```
[%$order.<fieldname>%]
```
shopping cart:
```
[%$cart.<fieldname>%]
```
box settings:
```
[%$setting.<settingname>%]
```

links:

[%$<linkname>.link%]
[%$<linkname>.text%]
[%$<linkname>.target%]

images:

[%$<imagename>.link%]
[%$<imagename>.text%]
[%$<imagename>.width%]
[%$<imagename>.height%]

If you are unsure of a variable, then you should ask us how to set it up.

Comments

Complete inline documentation comment blocks (docblocks) must be provided. Please read the phpDoc section to learn the specifics of writing docblocks. Further information can be found on the phpDocumentor website.

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. Preferred comment style is like that of phpDoc:

/*\*
* This is my comment for the following line of code
\*/
if(1 \!= 2) {
}

File Format

All scripts contributed to Batavi must:

Be stored as ASCII text
Use UTF-8 character encoding
Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

phpDoc

Following rules and examples are OBLIGATORY to implement in Batavi PHP files

The quality of documentation can be even more important than the quality of the code itself, as a good first impression will prompt developers to look further into your code. Automatic code documentation is implemented in Batavi to aid developers with functions that they are not familiar with and to improve PHP-code and object structure readability. It is based on specific comments describing classes, methods, interfaces and objects.

DocBlocks are comments located at the beginning of a file, or just before a class, a method, a function outside a class or a variable declaration. These comments will be parsed by PhpDocumentor to generate documentation. A DocBlock contains three basic segments in this order:

Short Description
Long Description
Tags

There are many ways of creating good documentation, but perhaps the best is to read what you have written from different perspectives. Open up your documentation, and try to use it to figure out your software project. If this is difficult, go back and edit or rewrite. Remove anything that is confusing or unnecessary, make sure everything is there that is needed.

DocBlocks Types

Page-level DocBlocks

This is one DocBlock for each PHP file. This describes the file used.

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * This file is part of Batavi Open E-Commerce Solution.
 *
 * Batavi Open E-Commerce Solution is free software: you can redistribute
 * it and/or modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation version 2 of the
 * License.
 * 
 * PHP versions 5
 * 
 * @copyright 2006 osCommerce Copyright
 * @copyright 2007-2008 Batavi Copyright
 * 
 * @author     Batavi, Open Source E-Commerce Solutions
 * @license    GNU General Public License v2
 * 
 * @link [http://www.gnu.org/licenses/]
 * @link [http://www.gnu.org/licenses/gpl-faq.html]
 */

Class DocBlocks

Class DocBlocks are blocks that describes a class.

/*\*
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @category   CategoryName
 * @package    PackageName
 * @copyright  2006 osCommerce Copyright
 * @copyright  2007-2008 Batavi Copyright
 * @license    GNU General Public License v2
 * @version    SVN: $ svn-revision-id $
 */

Method DocBlocks

A method is a function that is bound to a class. A method block describes this function.

/**
 * Short description - mandatory
 *
 * Long description - optional
 *
 * @param string $arg1 the string to quote
 * @param int       $arg2 an integer of how many problems happened.
 * <Indent to the description's starting point
 * for long ones.>
 *
 * @return int the integer of the set mode used. FALSE if foo
 * foo could not be set.
 * @throws exceptionclass [description]
 *
 * @access public
 * @static
 */

Class variable DocBlocks

Class variable DocBlocks are blocks that describe the variable within a class.

/**
 * The status of foo's universe
 *
 * Potential values are 'good', 'fair', 'poor' and 'unknown'.
 *
 * @var string
 */
public var $foo = 'unknown';

Function DocBlocks

Functions are almost the same as method but functions are not bound to a class.

/**
 * Short description - mandatory
 *
 * Long description - optional
 *
 * @param string $arg1 the string to quote
 * @param int       $arg2 an integer of how many problems happened.
 * <Indent to the description's starting point
 * for long ones.>
 *
 * @return int the integer of the set mode used. FALSE if foo
 * foo could not be set.
 * @throws exceptionclass [description]
 *
 * @access public
 * @static
 */

Require DocBlocks

DocBlocks describing requires.

/**
 * This is a "Docblock Comment," also known as a "docblock." The class'
 * docblock, below, contains a complete description of how to write these.
 */
require('test.php');

Include DocBlocks

/**
 * This is a "Docblock Comment," also known as a "docblock." The class'
 * docblock, below, contains a complete description of how to write these.
 */
include('test.php');

Define DocBlocks

DocBlock describing a define.

/**
 * Methods return this if they succeed
 */
define('SAMPLE', 1);

<big>DocBlocks Contents</big>

This are the most common used tags and contents. For more information look at the phpDocumentor site.

Short description

Mandatory for most DocBlocks, a one line description.

Long description

If needed, a longer description.

Example

Here is a code example. Please note: $simpleVariable doesn't need a description, but @var tag is mandatory. Here constructor doesn't need a description. getters and setters are too simple to have a description, but don't forget the @param and @return! use (but not abuse) of @link and @see. This can be really useful to navigate through documentation.

<?php
/**
 * Test file
 *
 * The purpose of this file is to show an example of how to use
 * PhpDocumentor DocBlocks in Batavi.
 *
 * PHP versions 5
 *
 * LICENSE: ...
 *
 * @category   CategoryName
 * @package    PackageName
 * @copyright  2008 Copyright Holder
 * @license    GNU General Public License v2
 * @version    SVN: $ svn-revision-id $
 */

/**
 * This is a require description
 */
require_once('required_file.php');

/**
 * This is a short description of btv_FooClass
 *
 * btv_FooClass long description.
 *
 * @category   myCategory
 * @package    myPackage
 * @copyright  2008 Copyright Holder
 * @license    GNU General Public License v2
 * @version    SVN: $ svn-revision-id $
 */
class btv_FooClass extends btv_SuperFooClass {
/**
 * @var int
 */
public $simple_variable;

/**
 * @var simple_object_variable
 */
public $simple_object_variable;

/**
 * This variable needs a description
 * @var string
 */
public $not_so_simple_variable;

/**
 * @param int
 */
function \__construct($initial_value) {
  parent::__construct();
  $this->simple_variable = $initial_value;
  $this->simple_object_variable = NULL;
  $this->not_so_simple_variable = '';
}

/**
 * @param int
 */
function setFooSimple($new_value) {
  $this->simple_variable = $new_value;
}

/**
 * @return int
 */
function getFooSimple() {
  return $this->simple_variable;
}

/**
 * This is a short description for method
 *
 * This is a longer description. Don't forget to have a
 * look here {@link MyLinkClass::myLinkMethod()}. blah blah.
 * @param string description of first parameter
 * @param second_parameter description of second parameter
 * @return boolean true if everything's fine
 * @see fooInterestingClass
 */
function fooMethod($first_parameter, $second_parameter) {
  /**
   * comment text (not added in phpDoc)
   */
  return true;
}

/**
 * @see fooInterface::myImplementingMethod()
 */
function myImplementingMethod($bar) {
  /**
   * comment text (not added in phpDoc)
   */
  return true;
}
}

function fooOverridingMethod($bar) {
  /**
   * comment text (not added in phpDoc)
   */
  return true;
}
}
?>

WIKI Documentation

Developers

Wherever needed the generated PHP Documentor documentation should be extended in the WIKI with extra information and examples.

Users

If features are added/modified in the admin/shop UI then this should be clearly documented how to use this features and what the possibilities are with it.

Page Operations

Browse Space

PHP

Labels:

Introduction

General coding rules

Paths

E_STRICT-compatible code

PHP

Coding Style

Indent

Control structures

Use of parenthesis and equals sign

Function calls

Function declarations

Class Modifiers

PHP Code Tags

Naming Conventions

Classes

Functions and Methods

Variables

Query variables

Box variables

Comments

File Format

phpDoc

DocBlocks Types

Page-level DocBlocks

Class DocBlocks

Method DocBlocks

Class variable DocBlocks

Function DocBlocks

Require DocBlocks

Include DocBlocks

Define DocBlocks

<big>DocBlocks Contents</big>

Short description

Long description

Tags

@copyright

@package

@subpackage

@version

@param

@return

@var

@access

Example

WIKI Documentation

Developers

Users