Code Style Guide

Perl
Formatting
Naming
Source Code Header and Charset
Version Comments
Special comments
Restrictions for some functions
Perldoc
Length of lines
Core-Objects
Objects and their allocation
Using of the MainObject
Using of the EncodeObject
Regular Expressions
JavaScript
Browser Handling
Directory Structure
Thirdparty Code
Variables
Functions
Namespaces
Comments
Event Handling
CSS
Architecture
Style

In order to preserve the consistent development of the OTRS project, we have set up guidelines regarding style for the different programming languages.

Perl

Formatting

TAB: We use 4 spaces. Examples for braces:

if ($Condition) {
    Foo();
}
else {
    Bar();
}

while ($Condition == 1) {
    Foo();
}
        

Naming

Names and comments are written in English. Variables, Objects and Methods must be descriptive nouns or noun phrases with the first letter set upper case.

e. g. @TicktIDs or $Output or BuildQueueView()
        

Source Code Header and Charset

Attach the following header to each and every source file. Source files are saved in Charset ISO-8859-1.

# --
# (file name) - a short description what it does
# Copyright (C) 2001-2011 OTRS AG, http://otrs.org/
# --
# $Id: perl.xml,v 1.3 2011-03-09 14:54:40 mb Exp $
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (AGPL). If you
# did not receive this file, see http://www.gnu.org/licenses/agpl.txt.
# --
        

Executable files (*.pl) have a special header.

#!/usr/bin/perl -w
# --
# (file name) - a short description what it does
# Copyright (C) 2001-2011 OTRS AG, http://otrs.org/
# --
# $Id: perl.xml,v 1.3 2011-03-09 14:54:40 mb Exp $
# --
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU AFFERO General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
# or see http://www.gnu.org/licenses/agpl.txt.
# --
        

The following line is updated by the CVS:

# $Id: perl.xml,v 1.3 2011-03-09 14:54:40 mb Exp $
        

Version Comments

Some functions may not be available in the current framework version. Thus, sometimes settings have to be changed when a new module and framework version will be released. If you use version comments, you can search for information (e.g. using grep) on what must be changed when a new version is published. The keyword for version comments is 'FRAMEWORK' For perl use '#' and for xml use the xml comments.

e.g. for perl-code
# FRAMEWORK-2.1: the function ID2UserName is first available in OTRS 2.1
        

Special comments

The only ways to create special comments are the following ways. Example 1 - especially for subactions of frontend modules

    # -----------------------------#
    # here starts a special area
    # -----------------------------#
            

Example 2 - especially for customizing standard OTRS files

    # --- customizing for bsi
            

Restrictions for some functions

Some functions are not useful in every script. Please pay attention to the following restrictions.

  • don't use "die" and "exit" in .pm-files

  • don't use the "Dumper" function in released files

  • don't use "print" in .pm files

  • use OTRS specific function "SystemTime2Date" instead of "localtime"

Perldoc

Every function which could be used outside of its package must have a perldoc. It should look like the following example.

=item SystemTime2TimeStamp()

returns a time stamp in "yyyy-mm-dd 23:59:59" format.

    my $TimeStamp = $TimeObject->SystemTime2TimeStamp(
        SystemTime => $SystemTime,
    );

If you need the short format "23:59:59" for dates that are "today",
pass the Type parameter like this:

    my $TimeStamp = $TimeObject->SystemTime2TimeStamp(
        SystemTime => $SystemTime,
        Type       => 'Short',
    );

=cut
            

Length of lines

Please see that a line of code is not longer then 100 charactars.

Core-Objects

Objects and their allocation

In OTRS many objects are available. But it is not allowed to use every object in each script. Please note the following definitions

  • don't use the LayoutObject in core modules

  • don't use the ParamObject in core modules

  • don't use the DBObject in frontend modules

Using of the MainObject

Information about the MainObject

  • initialize the MainObject in the basic .pl-file

  • in .pm files only pass it to the next Object you initialize

  • don't use the Perl "require" function any more

Using of the EncodeObject

Information about the EncodeObject

  • initialize the EncodeObject in the basic .pl-file

  • in .pm files only pass it to the next Object you initialize

Regular Expressions

For regular expressions we always use the m// operator with curly braces as delimiters. We also use the modifiers x, m and s. The x modifiers allows you two comment your regex and use spaces to "group" logical groups.

    $Date =~ m{ \A \d{4} - \d{2} - \d{2} \z }xms
    $Date =~ m{
        \A    # beginning of the string
        \d{4} - # year
        \d{2} - # month
        [^\n]   # everything but newline
        #..
    }xms;

As the space has no longer a special meaning, you have to use a single character class to match a single space ( [ ]). If you want to match any whitespace you can use \s. In the regex, the dot ('.') includes the newline (whereas in regex without s modifier the dot means 'everything but newline'). If you want to match anything but newline, you have to use the negated single character class ([^\n]).

    $Text =~ m{
        Test
        [ ]    # there must be a space between 'Test' and 'Regex'
        Regex
    }xms;

JavaScript

Browser Handling

All JavaScript is loaded in all browsers (no browser hacks in the .dtl files). The code is responsible to decide if it has to skip or execute certain parts of itself only in certain browsers.

Directory Structure

Directory structure inside the js/ folder:

* js
    * thirdparty              # thirdparty libs always have the version number inside the directory
        * ckeditor-3.0.1
        * jquery-1.3.2
    * Core.Agent.*            # stuff specific to the agent interface
    * Core.Customer.*         # customer interface
    * Core.*                  # common API
            

Thirdparty Code

Every thirdparty module gets its own subdirectory: "module name"-"version number" (e.g. ckeditor-3.0.1, jquery-1.3.2). Inside of that, file names should not have a version number or postfix included (wrong: jquery/jquery-1.4.3.min.js, right: jquery-1.4.3/jquery.js).

Variables

  • Variable names should be CamelCase, just like in Perl.

  • Variables that hold a jQuery object should start with $, for example: $Tooltip.

Functions

  • Function names should be !CamelCase, just like in Perl.

Namespaces

  • TODO...

Comments

  • Single line comments are done with //.

  • Longer comments are done with /* ... */

  • If you comment out parts of your JavaScript code, only use // because /* .. */ can cause problems with Regular Expressions in the code.

Event Handling

  • Always use $.bind() instead of the event-shorthand methods of jQuery for better readability (wrong: $SomeObject.click(...), right: $SomeObject.bind('click', ...).

  • Do not use $.live()! We had severe performance issues with $.live() in correlation with mouse events. Until it can be verified that $.live() works with other event types without problems.

  • If you $.bind() events, make sure to $.unbind() them beforehand, to make sure that events will not be bound twice, should the code be executed another time.

CSS

  • Minimum resolution is 1024x768px.

  • The layout is liquid, which means that if the screen is wider, the space will be used.

  • Absolute size measurements should be specified in px to have a consistent look on many platforms and browsers.

  • Documentation is made with CSSDOC (see CSS files for examples). All logical blocks should have a CSSDOC comment.

Architecture

  • We follow the Object Oriented CSS approach. In essence, this means that the layout is achieved by combining different generic building blocks to realize a particular design.

  • Wherever possible, module specific design should not be used. Therefore we also do not work with IDs on the body element, for example, if it can be avoided.

Style

  • All definitions have a { in the same line as the selector, all rules are defined in one row per rule, the definition ends with a row with a single } in it. See the following example:

    #Selector {
        width: 10px;
        height: 20px;
        padding: 4px;
    }
                        

  • Between : and the rule value, there is a space

  • Every rule has an indent of 4 spaces.

  • If multiple selectors are specified, separate them with comma and put each one on an own line:

    #Selector1,
    #Selector2,
    #Selector3 {
        width: 10px;
    }
                        

  • If rules are combinable, combine them (e.g. combine background-position, background-image, ... into background).

  • Rules should be in a logical order within a definition (all color specific rule together, all positioning rules together, ...).

  • All IDs and Names are written in CamelCase notation:

    <div class="NavigationBar" id="AdminMenu"></div>