Development > Topic

coding conventions/#1209

Jun 12, 2006 / pixtur
Jan 5, 2009 / phsouzacruz
 

Attached files

No files uploaded
 
Our coding guidelines are based on mantis:
http://www.mantisbt.org/guidelines.php

with some extensions / changes:

General Formatπ

  • Do not use TAB-Characters
  • Indention width is four spaces
  • Use a UTF8-capable editor for translating
  • Use Unix-Style Linebreaks

Use blocks to group some codeπ

### does something ###
{
   function1();
   function2();
}



Commentsπ

  • There are two types of comments:
  • First Letter of comments should be uppercase.

### Try to get comments ###

/**
* Short statement
*
* here comes a lot more of details information and
* comments and todo and stuff like this
*
* @Note Some notes
* @Todo We should fix this later
*/
  • use single `#` only for temporarily disabled code or at end of line.
# disabledFunction();

Labeling Functions, Variables and Classesπ

  • Functions in camelCase();
  • Names of functions returning html-code should start with render.
  • Names of functions printing html-code should start with print.
  • Global variables (except $PH and $auth) should start with $g_.
  • Variables holding already escaped html-code (escaped by asHtml()-function) should start with $html_. This string can be echoed without risking exececution of JavaScript-Code.

Spacingπ

When assembling strings, add spaces before and after ".":
$html_together= asHtml('I am ' . ' different');

Note that the above example is not good style, because it contains strings that are translatable. It should therefore be written as:
$html_together= asHtml(__('I am') .' ' . __('different'));

Or even better:
$html_together= asHtml( sprintf(__('I am %s.'), __('different')));

Codingπ

  • the ?: construct is okay in the following way:
$message= ($flag == true) 
       ? "is true"
       : "is false";
  • always open block after if:
 if($this_is_bad) $maybe=true;  # wrong

 if($this_is_good) {             # better
    $maybe= true;
 }
  • If you insert debug output, do it like...
 echo "%% some debug";
The %% will be found by the unit tests. Do not forget to deleted those before committing.

General php thingsπ

  1. Use echo instead of print.
  2. Avoid referenced function parameters.

Text and translatable stringsπ

Only use double quotes, if variables have to be evaluated in the string:
$single= 'I am a single';
$double= "We are $how_many";

Textoutput for users should always be enclosed into the translate function. Read more at Translation Guide .
echo 'Some people cannot read English';  # bad
echo __('That´s why we need translation'); # better

Make sure to not add any trailing or leading spaces, quotes or formatting stuff to the string:
$bad_habbit = __("-- don't change --");
$much_better = '-- ' .  __('don´t change') . ' --';


Special Hints for Doxygenπ

We use Doxygen to automatically create a documentation on the source code. For this to work, you need to add doc style comments before classes and functions. Example:

from example_file.inc.php

<?php if(!function_exists('startedIndexPhp')) { header("location:../index.php"); exit();}
# streber - a php5 based project management system  (c) 2005-2007  / www.streber-pm.org
# Distributed under the terms and conditions of the GPL as stated in lang/license.html

/** @file example file */

/**
* Just an example class
*
* @ingroup render
*
* There comes the detailed help with some comments as list:
* - point 1
* - point 2
*/
class someClass
{

  /** 
  * additional feature 
  * TODO fill in some code
  */
  function blub()
  {
  }
}
?>

Groupsπ

We split the source code into following groups:
  • render - anything related to rendering output
  • render_lists - anything related to list blocks an rendering lists
  • pages - for all page functions
  • wiki - function for rendering wiki
  • data - anything related to backend objects like Person, Task etc.

The @file commandπ

  • you are required to place a @file comment at the beginning for each new source file. Please do not forget this.

Special commands in commentsπ

  • Use @TODO in your comments to keep track on construction sites. Doxygen will list those places in a separate list.


read more at: http://www.stack.nl/~dimitri/doxygen/docblocks.html



also see:

6 Comments

madlyr:use of tab characters?

11 years ago (2. update 10 years ago)

I see that default tab is 4 spaces and code is mainly formatted by spaces. Is it allowed to use tabs?

tino:Reply to use of tab characters?

11 years ago

Hello Radoslav,

I'm using tabs - I think you can use it!


regards Tino

pixtur:No! Please do not use Tabs...

11 years ago

Sorry for being a little bit retarted with this, but since I am working on PC using tab-chacters always confuses my SVN/Diff tools. Please do not use tabs.

I added some more hints about.

tino:Reply to No! Please do not use Tabs...

11 years ago

okay

palobo:One quick question...

10 years ago

I know that it is very late in the game for such an idea, but wouldn't it be worth looking into refactoring the code and using some sort of framework?

I'm sure it would make maintainability a lot easier and also make it easier to scale.

Just my two cents..

pixtur:Antwort auf One quick question...

9 years ago

Yeah... this is a little bit late :) It would mean a complete rewrite of streber...