Torrus Programming Style Guide

Perl indentation style

The code indentation style is a kind of BSD/Allman style:

    while( not $success and time() < $waitingTimeout )
    {
        $self->clearReader();

        Info('Sleeping ' . $Torrus::Global::ConfigReadyRetryPeriod .
              ' seconds');
        sleep $Torrus::Global::ConfigReadyRetryPeriod;

        $self->setReader();

        if( $self->isReady() )
        {
            $success = 1;
            Info('Now configuration is ready');
        }
        else
        {
            Info('Configuration is still not ready');
        }
    }

Indentation is 4 characters. Opening and closing braces are aligned. There's no space between the keyword (while, if, etc.) and the opening parenthesis.

Tab characters are prohibited.

Page width is strictly 80 characters. All longer lines must be wrapped.

When possible, leave space between parentheses and the inside content. This is not necessary for debug or print statements.

There's always space around the equal sign (=).

The object method calls always have parentheses, even if no arguments are reqiured.

Use keywords for logical operations instead of C operators: and, or, not.

Use single quotes in hash references: $a->{'abc'}.

Common file properties

With the exception of special-purpose files, each source file must ontain the GNU copying statement, CVS Id tag, and author's name and e-mail address.

C, Perl, and Bourne shell files must contain Gnu Emacs variables at the end of the file:

 # Local Variables:
 # mode: perl
 # indent-tabs-mode: nil
 # perl-indent-level: 4
 # End:

Each file must always end with the linebreak. Otherwise it might conflict with CVS. All files must have Unix linebreak format.

GNU Emacs settings

Standard perl-mode.el does the thing:

 ;; Set up Perl mode
 (autoload 'perl-mode "perl-mode")
 (setq auto-mode-alist
     (append (list (cons "\\.pl$" 'perl-mode)
                   (cons "\\.pm$" 'perl-mode)
                   (cons "\\.pl\\.cgi$" 'perl-mode))
             auto-mode-alist))

 (custom-set-variables
   ;; custom-set-variables was added by Custom -- don't edit or cut/paste it!
   ;; Your init file should contain only one such instance.
  '(indent-tabs-mode nil)
  '(tab-width 8)
  )

X-Emacs settings

In X-Emacs, the default handler for Perl files is cperl-mode.el. The following custom variables must be set in order to comply to our styling standards:

 (custom-set-variables
   ;; custom-set-variables was added by Custom -- don't edit or cut/paste it!
   ;; Your init file should contain only one such instance.
  '(cperl-brace-offset -4)
  '(cperl-continued-statement-offset 4)
  '(cperl-indent-level 4)
  '(indent-tabs-mode nil)
  '(tab-width 8)
  )

Normalizing multiple files

In Torrus CVS repository, in the root of module src, there is a small utility that fixes some styling issues for all the sources in current directory and subdirectories:

  perl normalize-all-sources.pl