Difference between revisions of "Coding guidelines"

Revision as of 13:57, 21 July 2010

To make sure Group-Office will be developed with a unified coding structure and Graphical user interface the following guidelines have been created. Please follow all of these guidelines at all times. /etc/php.ini

1. Always use <?php tags and not <?. Since latest default PHP setups won't accept <? anymore.
2. Always code with register_globals=off for the same reason as in point 1.
3. Always make sure it will work with magic_quotes_gpc on and off by using the functions smart_stripslashes() and smart_addslashes(). These function work like stripslashes() and addslashes() but check the magic_quotes_gpc setting and thus determine if the operation is needed. So if you want to make sure a variable is escaped by slashes after a POST or GET operation you should use smart_addslashes(); This way it will never escaped twice. If you want to make sure a variable is not escaped then use smart_stripslashes();.
4. Turn on notices by setting error_reporting=E_ALL. This is very important because you will find errors easier with this setting enabled and Group-Office might not function properly on systems that do have this enabled and you have not. This also means that you'll have to declare every variable.

Coding structure

1. Use single quotes rather then double quotes for consistency in the look of the code.
2. Create functions in the following form:

   /***

   * Short description of the function

   *

   * More detailed multiline description

   *

   * @param string $example_var1 This is the var's desciption

   * @param string $example_var2 This is the var's desciption

   * @access public

   * @return bool Return value description

   */

   function example($example_var1, $example_var2)

   {

   //this is a comment

   if($example_var1)

   {

   $example_var1 = '';

   }else

   {

   $example_var2 = '';

   }

   return true;

3. Comment code that is not instantly clear by just reading it.
4. Don't double code. Try to re-use every single line of code on other pages. So when something changes there is only place to edit. Group-Office is build up out of classes. These classes perform the database operations and other backend operations.

Javascript

1. Put each component in a separate file to keep code clean and small. Files will be merged into one minified file anyway.
2. Start files with a capital letter and each word too (eg. CompanyDialog.js).
3. Put everything into it's module namespace. (eg. GO.addressbook, GO.addressbook.CompanyDialog)
4. Make all panels reusable if possible. Avoid multiple components that do almost the same. Make one that is configurable for all cases.

SQL escaping

Always use the db::escape() function on all SQL arguments. And also put quotes around arguments:

BAD: $sql = "SELECT * FROM table WHERE id=$id"; GOOD $sql = "SELECT * FROM table WHERE id='".$this->escape($db)."'";

The escape function and quotes are needed to prevent users from injecting SQL.

Miscellaneous

1. Group-Office already offers a wide variety of standard functions and classes. Always use these functions and don't reinvent the wheel! The best way to find out what functions are available is to take a look at the files: 'functions.inc', 'classes/base/*.security.class.inc', classes/base/controls/* and Group-Office.php.
2. Add a comment block on top with your name and email and version number like this (The two stars are important because PHPDoc doesn't work if you don't put two stars on top):

   /**

   * Copyright Intermesh

   *

   * This file is part of Group-Office. You should have received a copy of the

   * Group-Office license along with Group-Office. See the file /LICENSE.TXT

   *

   * If you have questions write an e-mail to info@intermesh.nl

   *

   * @copyright Copyright Intermesh

   * @version $Id

   Group-Office.php 2950 2008-09-03 08:39:41Z mschering $

   * @author Merijn Schering <mschering@intermesh.nl>

   */

3. Use a Tab space of 2
4. Keep code 80 characters wide so it's printable.
5. Never remove code from somebody else. If you do want to replace code then comment it out and put your name and e-mail address in the comment block. This way the original author can review the change and contact you if necessary.
6. Always make use of Group-Office multilingual system. Don hard code language in your code but put them in external language files.