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
- Use
echo instead of print.
- 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.