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