Coding conventions used in PeopleAggregator

From PeopleAggregator

Contents 1 Indentation 2 Optional braces 3 Page Header 4 General guidelines

[edit] Indentation

• Using spaces instead of tabs. Tabs are of different width in every editor. So using spaces instead of tabs is a good idea. Configure your editor to 'Use spaces instead of tabs'. In PeopleAggregator we use two spaces for general indentation. Two spaces are enough to understand your code flow. So we restrict our tab width to 2 spaces.

• 80 column width of a line. Most of the command line editors work best with 80 column width of a line. If we restrict our line width to 80 columns then our code is easy to understand when using command line editors like vi.

• Indentation with functions. Use no space between function name and opening braces. e.g.

 function foo(

• • No space between first parameter and opening braces also no space between last parameter and closing braces. e.g.

 function foo($param1, $param2)

• • In case of multiple parameters use comma and space between each parameter e.g.

 function foo($param1, $param2, $param3, $param4, $param5, $param6)

• Indentation with keywords. Put one space between keyword and opening parenthesis e.g

 if ($condition)

• Block level if - else or functions. Use K & R style. Put opening braces one space after the closing parenthesis on the same line e.g.

 if ($condition) {
   //php code
 } else {
   //php code
 }

• Operator. Use one space before and after any operator. e.g.

 for ($i = 0; $i < $size; $i++) {
   //some php code
 }

[edit] Optional braces

• Never omit optional braces. e.g.

 if ($condition) print 'Foo';// bad practice

 if ($condition) {
   print 'Foo';// good practice
 }

[edit] Page Header

• Use header on top of every page telling description of that file. e.g.

 /**
* Project:     PeopleAggregator: a social network developement platform
* File:        homepage.php, web file to display homepage contents
* @author:     Tekriti Software (http://www.tekritisoftware.com)
* Version:     1.1
* Description: This file displays the main page of the site. It uses
*              PageRenderer to display the block modules.
* The latest version of PeopleAggregator can be obtained from:
* http://peopleaggregator.org
* For questions, help, comments, discussion, etc., please visit 
* http://wiki.peopleaggregator.org/index.php
*
*/

• Function definition. While defining any function write purpose, parameters type and return type on top of that. e.g.

 /**
* Function: setup_module()
* Purpose:  call back function to set up variables 
*           used in PageRenderer class
*           To see how it is used see api/PageRenderer/PageRenderer.php 
* @param    $column - string - contains left, middle, right
*           position of the block module 
* @param    $moduleName - string - contains name of the block module
* @param    $obj - object - object reference of the block module
* @return   type string - returns skip means skip the block module
*           returns rendered html code of block module
*/
 function setup_module($column, $moduleName, $obj) {
   //code of function
 }

• Class Definition. Write brief description of the class on top of the class definition.

 /**
* This class generates inner html for the facewall
* gets links from calling pages - list of users
* @package BlockModules
* @subpackage Facewall
*/
 class FacewallModule{
   // class description
 }

[edit] General guidelines

• No assignment to undefined arrays. That is sloppy and error prone. Always go

 $results = array();
 Before
 $results[$i] = $value;

• Don't rely upon operator precedence and always use parenthesis.

• Never repeat the same sub-expression in the code. If you use a sub-expression more than once put it in a local variable. Local variables are not expensive. Also use descriptive names for variables.

• Doing same thing again and again makes code hard to read and expensive. This includes multiple repeated references like $this->foo or $dict['foo']. Never repeat $this->foo or $dict['foo'] instead put it in a local variable and use that.

• When making a for loop calculate the limit before the loop and put it in local variable instead of recalculating it each time with

for ($i = 0; $i < count($array); $i++) // here count function gets executed a lot of times

• Assign variables just before they are used, not scattered around the functions away from the code that depends upon them.