doc/programmierstilrichtlinien.txt

   1 Lx-Office Style Guide
   2 ---------------------
   3
   4 Die folgenden Regeln haben das Ziel, den Code möglichst gut les- und wartbar
   5 zu machen. Dazu gehört zum Einen, dass der Code einheitlich eingerückt ist,
   6 aber auch, dass Mehrdeutigkeit so weit es geht vermieden wird (Stichworte
   7 "Klammern" oder "Hash-Keys").
   8
   9 Diese Regeln sind keine Schikane, sondern erleichtern allen das Leben!
  10
  11 Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen.
  12 Einige der Regeln lassen sich automatisch überprüfen, andere nicht.
  13
  14 --------------------------------------------------------------------------
  15
  16 1. Es werden keine echten iTabs sondern Leerzeichen verwendet.
  17
  18 2. Die Einrückung beträgt zwei Leerzeichen.
  19    Beispiel:
  20
  21    foreach my $row (@data) {
  22      if ($flag) {
  23        # do something with $row
  24      }
  25
  26      if ($use_modules) {
  27        $row->{modules} = MODULE->retrieve(
  28          id   => $row->{id},
  29          date => $use_now ? localtime() : $row->{time},
  30        );
  31      }
  32
  33      $report->add($row);
  34    }
  35
  36
  37 3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
  38    der letzte Befehl.
  39    Beispiele:
  40
  41    sub debug {
  42      ...
  43    }
  44
  45    oder
  46
  47    if ($form->{item_rows} > 0) {
  48      ...
  49    }
  50
  51 4. Schließende geschweifte Klammern sind so weit eingerückt wie der Befehl/
  52    die öffnende schließende Klammer, die den Block gestartet hat, und nicht
  53    auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten.
  54
  55 5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen
  56    Zeile wie schließende geschweifte Klammern.
  57    Beispiele:
  58
  59    if ($form->{sum} > 1000) {
  60      ...
  61    } elsif ($form->{sum} > 0) {
  62      ...
  63    } else {
  64      ...
  65    }
  66
  67    do {
  68      ...
  69    } until ($a > 0);
  70
  71 6. Parameter von Funktionsaufrufen müssen mit runden Klammern versehen
  72    werden. Davon nicht betroffen sind interne perl Funktionen,
  73    und grep ähnliche Operatoren.
  74
  75    Beispiel:
  76
  77    $main::lxdebug->message("Could not find file.");
  78    %options = map { $_ => 1 } grep { !/^#/ } @config_file;
  79
  80 7. Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:
  81
  82   Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen
  83   abgesetzt werden. Logische Klammerungen ebensowenig, Blöcke schon.
  84
  85
  86   Beispiel:
  87
  88       if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
  89         ...
  90       }
  91
  92       $array[$i + 1]             = 4;
  93       $form->{sum}              += $form->{"row_$i"};
  94       $form->{ $form->{index} } += 1;
  95
  96       map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;
  97
  98 8. Mehrzeilige Befehle
  99
 100   8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen
 101       aufgeteilt, so sollten diese bis zu der Spalte eingerückt werden,
 102       in der die ersten Funktionsparameter in der ersten Zeile stehen.
 103       Beispiel:
 104
 105       $sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
 106                            $form->{some_col_value});
 107
 108   8.3 Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer
 109       übersichtlichen Tabellenstruktur organisiert wird.
 110
 111       Beispiel:
 112
 113       my $rowcount = $form->{"row_$i"} ? $i
 114                    : $form->{oldcount} ? $form->{oldcount} + 1
 115                    :                     $form->{rowcount} - $form->{rowbase};
 116
 117 9. Kommentare
 118
 119   9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der
 120       Code eingerückt sein.
 121   9.2 Seitliche hängende Kommentare sollten einheitlich formatiert werden.
 122
 123   9.3 Sämtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch
 124       zu verfassen. So wie ich keine Lust habe französischen Quelltext zu lesen,
 125       sollte auch der Lx-Office Quelltext für nicht-Deutschsprachige lesbar sein.
 126
 127       Beispiel:
 128
 129       my $found = 0;
 130       while (1) {
 131         last if $found;
 132
 133         # complicated check
 134         $found = 1 if //
 135       }
 136
 137       $i = 0         # initialize $i
 138       $n = $i;       # save $i
 139       $i *= $const;  # do something crazy
 140       $i = $n;       # recover $i
 141
 142 10. Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation
 143     gewünscht ist.
 144
 145     Beispiele:
 146
 147     $form->{sum}      = 0;
 148     $form->{"row_$i"} = $form->{"row_$i"} - 5;
 149     $some_hash{42}    = 54;
 150
 151 11. Die maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen <= 79
 152     helfen unter bestimmten Bedingungen, aber wenn die Lesbarkeit unter
 153     kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann
 154     ist Lesbarkeit vorzuziehen.
 155
 156     Als Beispiel sei print_options aus bin/mozilla/io.pl angeführt.
 157
 158 12. Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerwünscht.
 159     Sie führen zu unnötigen Whitespaceänderungen die diffs verfälschen.
 160
 161     Emacs und vim haben beide recht einfache Methoden dafür:
 162     emacs kennt das Kommande nuke-trailing-whitespace,
 163     vim macht das gleiche manuell über :%s/\s\+$//e, mit
 164       :au BufWritePre * :%s/\s\+$//e
 165     wird das an speichern gebunden.
 166
 167 12. Es wird kein perltidy verwendet.
 168
 169     In der Vergangenheit wurde versucht perltidy zu verwenden um einen
 170     einheitlichen Stil zu erlangen, es hat sich aber gezeigt, dass Perltidys
 171     sehr eigenwilliges Verhaltes was Zeilenumbrüche angeht oftmals gut
 172     formatierten Code zerstört. Für den Interessierten sind hier die perltidy
 173     Optionen, die grob den beschriebenen Richtlinien entsprechen.
 174
 175   -syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
 176   -aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
 177   -lp -vt=1 -vtc=1
 178
 179 13. STDERR ist tabu. Unkonditionale Debugmeldungen auch.
 180
 181     Lx-Office bietet mit dem LXDebug Modul einen brauchbaren Trace/Debug
 182     Mechanismus, es gibt also keinen Grund nach STDERR zu schreiben.
 183
 184     Die LXDebug Methode "message" nimmt als ersten Paramter außerdem eine
 185     Flagmaske, für die die Meldung angezeigt wird, wobei "0" immer angezeigt
 186     wird. Sollte Meldungen sollten nicht eingecheckt werden, und werden in den
 187     meisten Fällen auch vom Repository zurückgewiesen.
 188
 189 14. Alle neuen Module müssen use strict verwenden.
 190
 191     $form, $auth, $locale, $lxdebug und %myconfig werden derzeit aus dem main
 192     package importiert. Alle anderen Konstrukte sollten lexikalisch lokal
 193     gehalten werden.