torrus/doc/devdoc/progstyle.pod

   1 #  rpnexpr.pod - Torrus RPN expressions guide
   2 #  Copyright (C) 2002  Stanislav Sinyagin
   3 #
   4 #  This program is free software; you can redistribute it and/or modify
   5 #  it under the terms of the GNU General Public License as published by
   6 #  the Free Software Foundation; either version 2 of the License, or
   7 #  (at your option) any later version.
   8 #
   9 #  This program is distributed in the hope that it will be useful,
  10 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 #  GNU General Public License for more details.
  13 #
  14 #  You should have received a copy of the GNU General Public License
  15 #  along with this program; if not, write to the Free Software
  16 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  17
  18 # $Id: progstyle.pod,v 1.1 2010-12-27 00:04:37 ivan Exp $
  19 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  20 #
  21 #
  22
  23 =head1 Torrus Programming Style Guide
  24
  25 =head2 Perl indentation style
  26
  27 The code indentation style is a kind of BSD/Allman style:
  28
  29     while( not $success and time() < $waitingTimeout )
  30     {
  31         $self->clearReader();
  32
  33         Info('Sleeping ' . $Torrus::Global::ConfigReadyRetryPeriod .
  34               ' seconds');
  35         sleep $Torrus::Global::ConfigReadyRetryPeriod;
  36
  37         $self->setReader();
  38
  39         if( $self->isReady() )
  40         {
  41             $success = 1;
  42             Info('Now configuration is ready');
  43         }
  44         else
  45         {
  46             Info('Configuration is still not ready');
  47         }
  48     }
  49
  50
  51 Indentation is 4 characters. Opening and closing braces are aligned.
  52 There's no space between the keyword (C<while>, C<if>, etc.) and the opening
  53 parenthesis.
  54
  55 Tab characters are prohibited.
  56
  57 Page width is strictly 80 characters. All longer lines must be wrapped.
  58
  59 When possible, leave space between parentheses and the inside content.
  60 This is not necessary for debug or print statements.
  61
  62 There's always space around the equal sign (C<=>).
  63
  64 The object method calls always have parentheses, even if no arguments are
  65 reqiured.
  66
  67 Use keywords for logical operations instead of C operators: C<and>, C<or>,
  68 C<not>.
  69
  70 Use single quotes in hash references: C<$a-E<gt>{'abc'}>.
  71
  72 =head2 Common file properties
  73
  74 With the exception of special-purpose files, each source file
  75 must ontain the GNU copying statement, CVS C<Id> tag, and author's name and
  76 e-mail address.
  77
  78 C, Perl, and Bourne shell files must contain Gnu Emacs variables
  79 at the end of the file:
  80
  81  # Local Variables:
  82  # mode: perl
  83  # indent-tabs-mode: nil
  84  # perl-indent-level: 4
  85  # End:
  86
  87 Each file must always end with the linebreak. Otherwise it might conflict
  88 with CVS. All files must have Unix linebreak format.
  89
  90 =head2 GNU Emacs settings
  91
  92 Standard C<perl-mode.el> does the thing:
  93
  94  ;; Set up Perl mode
  95  (autoload 'perl-mode "perl-mode")
  96  (setq auto-mode-alist
  97      (append (list (cons "\\.pl$" 'perl-mode)
  98                    (cons "\\.pm$" 'perl-mode)
  99                    (cons "\\.pl\\.cgi$" 'perl-mode))
 100              auto-mode-alist))
 101
 102  (custom-set-variables
 103    ;; custom-set-variables was added by Custom -- don't edit or cut/paste it!
 104    ;; Your init file should contain only one such instance.
 105   '(indent-tabs-mode nil)
 106   '(tab-width 8)
 107   )
 108
 109 =head2 X-Emacs settings
 110
 111 In X-Emacs, the default handler for Perl files is C<cperl-mode.el>.
 112 The following custom variables must be set in order to comply to our styling
 113 standards:
 114
 115  (custom-set-variables
 116    ;; custom-set-variables was added by Custom -- don't edit or cut/paste it!
 117    ;; Your init file should contain only one such instance.
 118   '(cperl-brace-offset -4)
 119   '(cperl-continued-statement-offset 4)
 120   '(cperl-indent-level 4)
 121   '(indent-tabs-mode nil)
 122   '(tab-width 8)
 123   )
 124
 125 =head2 Normalizing multiple files
 126
 127 In Torrus CVS repository, in the root of module C<src>, there is a small
 128 utility that fixes some styling issues for all the sources in
 129 current directory and subdirectories:
 130
 131   perl normalize-all-sources.pl
 132
 133 It replaces tabs with spaces, deletes space at the end of line,
 134 and removes empty lines at the start and the end of file.
 135
 136 =head1 Author
 137
 138 Copyright (c) 2003-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>