Coding standards for phpShop

This document is blatant copy from CakePHP.

This document is somewhat based on PHP.PL DevTeam Coding standards.

Note: It is always good to look at some HTML markup reference.

Contents:

1. Coding standards for phpShop
2. Purpose of this document
   1. Adding new features
3. Indentation
4. Control structures
   1. Ternary Operator
5. Function calls
6. Method definition
7. Commenting code
8. Including files
9. PHP tags
10. Naming convention
    1. Functions
    2. Classes
    3. Variables
    4. Member visibility
    5. Example addresses
    6. Files
    7. Variable types
    8. Constants

Purpose of this document

Cake Developers will use the following coding standards.

It is recommended that others developing CakeIngredients? follow the same standards.

Adding new features

No new features should be added, without having their own tests - which should be passed before commiting them to the repository.

Indentation

One tab will be used for indentation.

So, indentation should look like this:

<?php
// base level
    // level 1
        // level 2
    // level 1
// base level
?> 

Control structures

Control structures are for example "if", "for", "foreach", "while", "switch" etc. Below, an example with "if":

<?php 
if ((expr_1) || (expr_2 )) { 
    // action_1;
} elseif (!(expr_3) && (expr_4)) {
    // action_2; 
} else {
    // default_action; 
} 
?>

In the control structures there should be 1 (one) space before the first parenthisis and 1 (one) space between the last parenthisis and the opening bracket.

Always use curly brackets in control structures, even if they are not needed. They increase the readability of the code, and they give you fewer logical errors.

Opening curly brackets should be placed on the same line as the control structure. Closing curly brackets should be placed on new lines, and they should have same indentation level as the control structure. The statement included in curly brackets should begin on a new line, and code contained within it should gain a new level of indentation.

<?php 
// wrong - no brackets, badly placed statement
if (expr) statement; 

// wrong - no brackets
if (expr) 
    statement; 

// good
if (expr) {
    statement;
}
?>

Ternary Operator

Do not use ternary operator (?:). We need Cake code base to be as readable as possible, and we believe that using full if-else calls will make code look better, more readable and maybe most important, easier to debug.

Function calls

Functions should be called without space between function's name and starting bracket. There should be one space between every parameter of a function call.

<?php 
$var = foo($bar, $bar2, $bar3); 
?>

As you can see above there should be one space on both sides of equals sign (=). To increase the redability of the code you can add spaces (or tabs) before the equals sign, but only in the case of a multiple function call presented below:

<?php 
$varShort     = foo($bar1);
$variableLong = foo($bar1);
?>

Method definition

Example of a function definition:

<?php 
function someFunction($arg1, $arg2 = '') {
    if (expr) {
        statement;
    }
    return $var;
}
?>

Parameters with a default value, should be placed last in function definition. Try to make your functions return something, at least true or false - so it can be determined whether the function call was successful.

<?php 
function connection(&$dsn, $persistent = false) {
    if (is_array($dns)) {
        $dns_info = &$dns;
    } else {
        $dns_info = BD::parseDNS(dns);
    }

    if (!($dns_info) || !($dns_info['phpType'])) {
        return $this->addError();
    }
    return true;
}
?>

Note that there are spaces on both side of the equals sign.

Commenting code

All comments should be written in English, and should in a clear way describe the commented block of code.

Comments can include the following phpDocumentator tags:

• @access
• @author
• @copyright
• @deprecated
• @example
• @ignore
• @internal
• @link
• @see
• @since
• @tutorial
• @version
• inline {@internal}}
• inline {@inheritdoc}}
• inline {@link}}

PhpDoc tags are very much like JavaDoc tags in Java. Tags are only processed if they are the first thing in a DocBlock line, for example:

<?php
/**
 * Tag example.
 * @author this tag is parsed, but this @version is ignored
 * @version 1.0 this tag is also parsed
 */
?>

There are 3 inline tags ({@internal}}, {@inheritdoc}} and {@link}}). Example:

<?php
/**
 * Example of inline phpDoc tags.
 *
 * This function works hard with {@link foo()} to rule the world.
 */
function bar() {
}

function foo() {
}
?>

Including files

When including files with classes or libraries, use only and always the require_once function.

PHP tags

Always use long tags:

<?php
?>

Never use short tags:

<?
?>

Naming convention

Functions

Function names should be written in camelBack?, for example:

<?php
function longFunctionName() {
}
?>

Classes

Class names should be written in CamelCase, for example:

<?php
class ExampleClass {
}
?>

Variables

Variable names should be as descriptive as possible, but also as short as possible. Normal variables should start with a lowercase letter, and should be written in camelBack? in case of multiple words. Variables containing objects should start with a capital letter, and in some way associate to the class the variable is an object of. Example:

<?php
$user = 'John';
$users = array('John', 'Hans', 'Arne');

$Dispatcher = new Dispatcher();
?>

Member visibility

As we cannot use PHP5's private and protected keywords for methods or variables, we agree on following rules:

• A protected method or variable name start with a single underscore ("_"). Example:

  <?php
  class A {
      var _iAmAProtectedVariable;
  
      function _iAmAProtectedMethod() {
          /*...*/
      }
  }
  ?>
  
  

• A private method or variable name start with double underscore ("__"). Example:

  <?php
  class A {
      var __iAmAPrivateVariable;
  
      function __iAmAPrivateMethod() {
          /*...*/
      }
  }
  ?>
  
  

Example addresses

For all example URL and mail addresses use "example.com", "example.org" and "example.net", for example:

• Email: someone@example.com
• WWW: http://www.example.com
• FTP: ftp://ftp.example.net

Files

File names should be created with lower case. If a file name consist of multiple words, they should be divided by an underscore character, for example:

• long_file_name.php

Variable types

Variable types for use in DocBlocks:

Type	Description
mixed	A variable with undefined (or multiple) type.
integer	Integer type variable (whole number).
float	Float type (point number).
boolean	Logical type (true or false).
string	String type (any value in "" or ' ').
array	Array type.
object	Object type.
resource	Resource type (returned by for example mysql_connect()).

Remember that when you specify the type as mixed, you should indicate whether it is unknown, or what the possible types are.

Constants

Constants should be defined in capital letters:

<?php
define('CONSTANT', 1);
?>

If a constant name consists of multiple words, they should be separated by an underscore character, for example:

<?php
define('LONG_NAMED_CONSTANT', 2);
?>