FacebookTwitterFlickrYoutuberss

Coding Style

From Zentyal Linux Small Business Server
Jump to: navigation, search

Contents

Coding style

A few coding style rules. Some of them make sense, some are just there to provide consistency across everybody's code.

Indentation

  • 4 spaces, no tabs. Basic Vim config:
set ai
set tabstop=4
set expandtab
set shiftwidth=4
set shiftround
  • ChangeLog files are the exception to this, they use tabs, the easiest thing you can do if your editor replaces spaces by tabs is copy&paste from one of the previous entries. Another option is to use this setting in your vim configuration:
autocmd BufNewFile,BufRead ChangeLog set tw=80 noexpandtab
  • Spaces at the end of the lines are not allowed, you can add this to .vimrc to highlight and autodelete them:
highlight RedundantWhitespace ctermbg=red guibg=red
match RedundantWhitespace /\s\+$\| \+\ze\t/
autocmd BufWritePre *.pm :%s/\s\+$//e
  • Never introduce more than one or two consecutive blank lines if there is not a good reason for it (and usually there isn't).

Comments

  • Public API methods needs to be documented.
  • The code in general should not be commented, it should be clean enough to not require comments, before writing a comment, first thing if you can make that code clean and self-explanatory.
  • Bad comment examples:
# constant declaration
use constant FOO => 3;

# do something with all the elements of the array
for my $i (@array) { doSomething($i); }
  • Good comment:
# FIXME: This function needs to be called to workaround the issue with the foobar 3.X package
# it can be removed as soon as the new upstream version fixes it
workaroundIssue();

Braces

For sub's opening brace goes on a new line, for any other code goes on the same line.

Example:

sub foo
{
    my ($bar) = @_;

    if ($bar) {
        $bar++;
    }
}

Spacing

Best explained with examples:

# right
if ($a < $b) {
    doStuff(3);
} else {
    doOtherStuff(3);
}

# wrong!
if( $a < $b ){
    doStuff (3);
}else{
    dontOtherStuff (3);
}

# perl keywords
split ('/', "foo/bar"); # right
split('/', "foo/bar");  # wrong!

# spacing around operators
my $foo = $bar + $foobar;  # right
my $foo=$bar+$foobar;      # wrong!
my $foo  = $bar + $foobar; # also wrong! (2 consecutive spaces)

Parameters

  • Use positional parameters with 3 or less arguments.
  • Use always a hash with named parameters for more than 3 arguments.
  • Always pass and return references, specially in public methods.
  • Take parameters from @_ on a single line instead of using shift.
  • Examples:
# right
sub foo
{
   my ($a, $b) = @_;
}

# wrong!
sub foo
{
   my $a = shift;
   my $b = shift;
}

# right
$object->foo(a => 1, b => 2, c => 3, d => 4);

sub foo
{
   my ($self, %params) = @_;

   my $a = $params{a};
   my $b = $params{b};
   my $c = $params{c};
   my $d = $params{d};
}

# wrong!
$object->foo(1, 2, 3, 4);

sub foo
{
    my ($self, $a, $b, $c, $d) = @_;
}

Naming

Basic naming:

  • CONSTANTS in uppercase (even if it's a regular $SCALAR_VARIABLE_USED_AS_CONSTANT).
  • Packages::Always::With:First::Letter::Uppercase
  • camelCase for variables and methods.

Some general rules taken from the Qt guidelines:

  • Do not abbreviate otherwise names will be more difficult to remember
  • Parameter names are an important source of information
  • Verbs have no prefix and don't use third person
  • Use prefix set for setters and avoid prefix for getters

As Perl syntax does not allow us to specify which methods are public, protected, or private we will stick to the following convention:

  • Public methods without any prefix
  • Protected methods will start with '_', and its documentation will reflect that
  • Private methods will start with '_'

Multi-line statements

  • When using multi-line statements, the same 4-space indentation rule prevails.
  • Examples:
# right (one line, everything ok)
my $foo = [ { a => 1, b => 2 }, { a => 3, b => 4 } ];

# right
my $foo = [
    { a => 1, b => 2 }, 
    { a => 3, b => 4 }
];

# wrong!
my $foo = [
                { a => 1, b => 2 }, 
                { a => 3, b => 4 }
          ];

# right
my $foo = [
    {
        a => 1, 
        b => 2 
    }, 
    {
        a => 3, 
        b => 4
    }
];

# wrong!
my $foo = [{
            a => 1, 
            b => 2 
           }, 
           {
            a => 3, 
            b => 4
           }];

Other rules

  • Never export symbols.
  • Never use the default variable ($_) except when there is no other option (map, grep, etc).
  • Always declare file handles as scalar variables:
# right
my $fh;
open ($fh, 'foo');

# wrong
open (FH, 'foo');
  • Never use AUTOLOAD unless there is a very good reason to do it.


Template:TracNotice

Personal tools
Namespaces

Variants
Actions

Zentyal Wiki

Zentyal Doc
Navigation
Toolbox