Coding Guidelines

In order to keep our code consistent, pretty and to be a developer, please use the following guidelines. We use a Coding Guideline very similar to PEAR Coding Standard Guidelines, with very little modifications.

  • Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. It’s the most portable way to include PHP code on differing operating systems and setups.
  • Indenting: Use an indent of 4 spaces, with no tabs.
  • If you are modifying someone else’s code _KEEP_ the coding style.
  • Use PHPdoc!! in your code!
  • Please use TODO: comment to indicate a missing implementation/feature
  • Tag your buggy code with the comment FIXME: and the description of the problem
  • Use a descriptive introduction for any new files, example:
/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * PHP versions 4 and 5
 *
 * LICENSE: Use GPL license for gadgets, LGPL for Core
 *
 * @category   Gadget/Core
 * @package    GadgetName/Core
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 Jaws Development Group
 * @license    URL to GPL or LGPL
 * @since      File available since Release 1.2.0
 */
  • Functions, method, variables and classes should be in Upper CamelCase:
// good
class FooBar 
{
    var $_Name;
    var $ID;
 
    function FooBar($param) 
    {
    }
}
 
//bad
class fooBar 
{
    var $_myName;
    var $id;
 
    function fooBar($param) 
    {
    }
}
  • Do not put a space after the opening parenthesis and the closing on, but write a space between each parameter. This applied for usage and class/method definition.
// good
$object->FooBar($a, $b, $c);
$array[10] = 'foo';
 
function FooBar($param1, $param2, $param3)
{
}
 
//bad
$object->FooBar( $a,$b, $c );
$array[ 10 ] = 'foo';
 
function FooBar($param1,$param2,$param3)
{
}
  • DO NOT write a blank space between the method name and the first parenthesis:
// good
$object->FooBar($a, $b, $c);
$array[10] = 'foo';
 
//bad
$object->FooBar ($a);
$array[ 10 ] = 'foo';
  • As practice, in your private variables write an underscore before the name of it:
// good
var $_Name //Private Var
 
//bad
var $Name //Private Var
  • In case you are using private vars and want to pass/get the value of your variable to/from another object. Write a method to retrieve it and avoid retrieving it directly.
// good
$otherObject = $anotherOne->GetName(); //Get the value of the private var, named $_Name.
 
//bad
$otherObject = $anotherOne->_Name; //Get the value of the private var, named $_Name.
  • Inside a code block, put the opening brace on the same line as the statement
// good
if ($a) {
   Foo();
   Bar();
}
 
// bad
if ($a)
{
   Foo();
   Bar();
}

  • Avoid skipping open/close braces, no matter what:
//good
if ($a) {
   Foo();
}
 
//bad
if ($a)
   Foo();
  • When defining a class/method, use the C style for brace placement, that means, use a new line for the brace, like this:
// good
class Foo extends Bar
{
   function Foo ()
   {
      // do something
   }
}
 
// bad
class Foo extends Bar  {
    function Foo () {
        // do something
    }
}
  • Long lines: It is recommended that you break lines at approximately 75-85 characters.
  • In the case of a block of related assignments, more space may be inserted to promote readability:
//good
$short         = FooBar($bar);
$long_variable = FooBar($baz);
 
//bad
$short = FooBar($bar);
$long_variable = FooBar($baz);
  • Concatenation in requires: When you want to concatenate a string with a PHP variable, can be done in different ways: using dots or using braces ({}):
//good
echo "My name is {$this->_Foobar}, urgh";
echo "My name is " . $this->_Foobar . ", urgh";
 
//bad, note there are missing spaces.
echo "My name is ".$this->_Foobar.", urgh";
  • Usage of “ and of ‘: This is a hard task and all developer should pay attention:
    • ” Should be used in more than one word and ' in single words.
//good
echo 'Foobar';
echo "My name is foobar";
 
//bad
echo "Foobar";
echo 'My name is foobar';
  • Array keys and defines should have single quotes:
//good
define('FOOBAR', 'BAR');
define('FOOBAR', "I am leaving");
 
$array = array();
$array['keyname'] = 'value';
 
//bad
define("FOOBAR", 'BAR');
define("FOOBAR", "I am leaving");
 
$array = array();
$array["keyname"] = 'value'; //key has single quotes
$array["keyname"] = "value"; //key and value (one word) have double quotes.
  • Indentation: Use an indent of 4 spaces, with no tabs. If you use Emacs to edit PEAR code, you should set indent-tabs-mode to nil. ALL code should be indented.
//For Emacs, you need the php-mode and copy the following in your .emacs file
(defun php-mode-hook ()
  (setq tab-width 4
        c-basic-offset 4
        c-hanging-comment-ender-p nil
  	indent-tabs-mode
	(not
	 (and
	      (string-match "\.php$" (buffer-file-name))))))

(add-hook 'php-mode-user-hook 
	  'php-mode-hook)

//For Vim:
set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4

Happy coding! ;-)

(Based on this doc by the Pear Development Team).

 
  /var/www/wiki/htdocs/data/jaws/development/guidelines.txt · Last modified: 2007/11/02 16:27