Coding style

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

KISS

• code should be kept simple and readable. This should be a major priority.

Some examples of this:

        less readable: if (!condition) {
        more readable: unless (condition) {

        less readable: $foo->doSomeStuff(someArg, anotherArga) if (condition)
        more readable: if (condition) { 
                                $foo->doSomeStuff(...);
                        }

the shorter versions of if constructs are good when the code is small:

        checkData($arg) or die "wrong data"; # this is perfectly readable

but, the ones that put the condition before are more readable:

        die "Wrong data" unless checkData($arg); # this is less readable

Format

• Lines should be 80 characters wide unless there is a very good reason for doing so.
• Use 4 spaces for indentation purposes. Do not use tabs

Braces

Opening brace starts at the end of the line:

• Ending brace goes on a line by itself. Aligned with the opening line.

                  if () {
                          do stuff
                  }
  

  • else and elsif clauses go on the same line as the closing brace of the if:

                    if () {
                            do stuff
                    } else {
                            do other stuff
                    }
    

Spacing

Put spaces before and after parethesis, and braces they make everything more readable:

                wrong: if(someCondition){
                                do stuff
                       }else{
                                do other stuff
                       }

                right: if (someCondition) {
                                do stuff
                       } else {
                                do other stuff
                       }

Put spaces around operators:

                wrong: my $foo=$bar+$foobar;
                right: my $foo = $bar + $foobar;

Parameters

Method signature

• In case of having fewer than three parameters use positional parameters, otherwise named parameters.
• Avoid using flags in function taking more than one parameter. If necessary add a new method.

Passing parameters

• Always pass arrays and hashes by reference. It's faster.
• The sames goes to return arrays or hashes.

Fetching parameters

• If a method receives positional parameters, fetch all them at once, and do not use shift

  This is wrong:
  sub foo() {
     my $a = shift;
     my $b = shift;
  }
  
  This is right:
  sub foo() {
     my ($a, $b) = @_;
  }
  

Naming public methods

This section has been copied from  this great article of the Qt Guys on APIs.

• 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

Exporting symbols

Try to use an OO design as much as possible. If it happens you have to export functions, never export them by default. Use @EXPORT_OK, and the client modules will have to explicitly import them.

Package layout

Try to stick to the following file layout:

# Copyright (C) 2007 Warp Networks S.L.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License, version 2, as
# published by the Free Software Foundation.
#
# 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 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

# Class description using NaturalDocs syntax

package EBox::MyPackage; # Package name

use base 'EBox::GConfModule'; # Super classes

use strict;  # Always use this to catch errors
use warnings;

# EBox uses
use EBox;
use EBox;
use EBox::Exceptions::Internal;

# Other modules uses
use Net::Ldap;

# Constants
use constant PI => 3.1416;


# Public and protected methods
# Every public and protected method must be commented using NaturalDocs syntax
sub _create
{

}

sub action
{

}

sub setName
{

}

sub name
{

}

# Private helper functions
sub _computeSquareMean
{

}

sub _filterRogueNames
{

}

1;