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