You are browsing the documentation for iTop 2.7 which is not the current version.

Consider browsing to iTop 3.1 documentation

Combodo Coding Standards

This page is a brief description of the iTop coding conventions (mostly for PHP). The iTop coding conventions share a lot with the PSR-2 standard, but there are also quite a few significant differences, beware!

The source code files are encoded in UTF-8 (without a BOM at the beginning of the file).
The line feeds must be Lf.

PHP files must use the long PHP opening tag at the beginning of the file <?php but must not contain any PHP closing tag. This prevents extra blank characters to be added by mistake at the end of the file… where they will be appended to the output produced by the page.

In iTop, all the code is written in English: functions, variables, class names and comments are to be written in valid English.

Strings delimiter

You can use any of the delimiter you prefer, the main goal is to keep the code readable.

When using heredoc / nowdoc, we recommend using delimiters that allows JetBrains' language injection.

Examples :

$sHtml = '<a href="http://www.combodo.com">';
 
$sFooBarBaz = "{$foo}-{$bar} {$baz}";
 
$sJs = <<<JS
console.debug("this is some JS code");
console.debug("having the right delimiter keyword will help language injection !");
JS;

Variables naming

Variables, function parameters and object properties are named using a mixed case convention (i.e. all lowercase with an uppercase letter at the beginning of each word) and a prefix letter used as a type hint:

  • the a prefix is used for hash or arrays (PHP does not make any difference: each array is actually a hash)
  • the i prefix is used of for integers
  • the o prefix is used for PHP objects
  • the s prefix is used for strings
  • more rarely used: f for floating point numbers (i.e. non integer numbers), r or h can be used for resource handles.

Example:

<?php
 
$iCount = 1;
$sText = 'This is a text';
$oPage = new WebPage('test');
$fRank = 1.25;
$hDir = opendir('/opt');
 
// No PHP closing tag

A variable with no prefix is supposed to be of mixed type (can be either a string, an array or an object)

Example:

public function Set($sAttCode, $value)
{
    ...
}

Allowed Exceptions

  • Local variables used for loop counters (e.g. $i, $j) may have no prefix.
  • In mathematical computations involving a lot of numeric variables it is acceptable to drop the prefix for such variables (e.g. $x, $y, $xMax…)
  • For historical reasons, the WebPage class (and the related classes) as well as some parts inside MetaModel use a different convention: variables are all lowercase with an underscore character to separate words. Object properties (members) are prefixed using the m_ prefix.

Array key naming

We are using Snake case for array keys.

Example :

$aMyArray = [
   'value_raw' => $sMyValue,
   'input_id' => $iInputId,
];

Configuration parameter naming

You shoud use lower case and separate words with an underscore character.

When multiple configuration parameters relates to the same subject, they can be grouped using a prefix ending with a dot character.

For example : email_transport_smtp.host

Functions naming (PHP, JS)

Functions and object methods are named using a mixed case convention (i.e. all lowercase with an uppercase letter at the beginning of each word). Even if PHP is not case sensitive for the function names, this useful to distinguish the functions which are part of the project from PHP's built-in functions which are generally written in lowercase. The function names are generally based on a verb expressing the action being performed.

Example:

function DisplayWelcomePopup(WebPage $oP)
{
    // Code goes here
}
Regarding visibility and other keywords order, the PSR-2 states :
Visibility MUST be declared on all properties and methods; abstract and final MUST be declared before the visibility; static MUST be declared after the visibility.

White spaces and indentation

Since 08/28/2020 this convention has changed. Base code will be updated on the fly (function by function when modifying for bug/enhancement reason).

The indentation is made using :

  • PHP files : tabulations (configure your editor to display a tab as 4 characters wide)
  • SCSS : 2 spaces
  • Twig : 4 spaces

Opening braces for if/else, try/catch, while, switch, anonymous classes must be at the end of the line, and closing braces must go on the next line after the body. For classes and functions we are keeping opening braces on the next line.

Example:

class NiceWebPage extends WebPage
{
    ...
 
    public function SetContentType($sContentType)
    {
        if ($sContentType == '') {
            // Do something
        } else {
            // Do something different
        }
    }
}

When writing function calls, the arguments supplied (between parentheses) immediately after the name of the function: there is no space between the function name and the arguments list. The comma in each arguments list is followed by a space.

Example:

$sValue = Utils::ReadParam('param1', 'default_value');

The binary operators (==, +, &&) are surrounded by spaces.

Exception: the concatenation operator . is not surrounded by spaces since this tends to keep lines more compact and does not reduce the readability of the code when using non-proportional fonts.

Example:

if (isset($aPerson[$this->iPersonId][0]) && ($aPerson[$this->iPersonId][0] != "")) {
   if ($this->sSynchronizeOrganization == 'yes') {
       $sName = $aPerson[$this->iPersonId]['first_name'].' '.$aPerson[$this->iPersonId]['last_name'];
   }
}

PhpDoc

The rules to write PhpDoc are described in the repository itself : see /.doc/README.md.

We are also using :

  • @since tags to indicate API methods introduction or modifications
  • Array Shapes syntax to document complex array structures

Dictionnaries entries

This is a subject by itself, see the dedicated wiki page : How to translate

2_7_0/customization/coding_standards.txt · Last modified: 2022/08/17 10:37 (external edit)
Back to top
Contact us