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 boolean flags in functions 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.

In general but specially for public methods:

  • 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 will not need any prefix
  • Protected methods will start with '_', and its documentation will reflect that
  • Private methods will start with '_'

When overriding a method it is mandatory to refer to the documentation of the class which declared it. 

# Method: validateRow
#
#       Override <EBox::Model::DataTable::validateRow> method
#
# Exceptions:
#
#       <EBox::Exceptions::External> - throw if interface is not
#       external or the rule cannot be built
#
#       <EBox::Exceptions::InvalidData> - throw if parameter has
#       invalid data
#
#

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.

STDOUT, STDERR

Never print stuff to STDOUT or STDERR directly. For debug purposes use EBox::debug().

File handles

Always declare file handles

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;

# Group: Public and protected methods __Optional__

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

}

sub action
{

}

sub setName
{

}

sub name
{

}

# Group: Private methods __This is optional__
# Private helper functions
sub _computeSquareMean
{

}

sub _filterRogueNames
{

}

1;