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 Zum einfachen Formartieren von Perl-Scripten gibt es das Tool "perltidy",
  12 das man weitgehend konfigurieren kann. Bei fast allen nachfolgenden Punkten
  13 sind die dazugehörigen perltidy-Optionen angegeben. perltidy ist bei den
  14 meisten Linux-Distributionen enthalten und kann ansonten unter
  15 http://perltidy.sourceforge.net heruntergeladen werden.
  16
  17 Jeder, der einen Patch schickt, sollte sein Script vorher durch perltidy
  18 laufen lassen. Damit werden einige der nachfolgenden Regeln automatisch
  19 befolgt, andere hingegen nicht. Dort, wo keine perltidy-Optionen angegeben
  20 sind, muss der Programmierer selbst für die Einhaltung sorgen.
  21
  22 --------------------------------------------------------------------------
  23
  24 1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet.
  25    Perltidy: -nt
  26
  27 2. Die Einrückung beträgt zwei Leerzeichen.
  28    Perltidy: -i=2
  29    Beispiel:
  30
  31    sub debug {
  32      print(STDERR "Debugging.\n");
  33    }
  34
  35 3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
  36    der letzte Befehl.
  37    Perltidy: -nbl -nsbl -bar
  38    Beispiele:
  39
  40    sub debug {
  41    ...
  42    }
  43
  44    oder
  45
  46    if ($form->{item_rows} > 0) {
  47      ...
  48    }
  49
  50 4. Schließende geschweifte Klammern sind so weit eingerückt wie der Befehl/
  51    die öffnende schließende Klammer, die den Block gestartet hat, und nicht
  52    auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten.
  53    Perltidy: macht's automatisch
  54
  55 5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen
  56    Zeile wie schließende geschweifte Klammern.
  57    Perltidy: -ce
  58    Beispiele:
  59
  60    if ($form->{"sum"} > 1000) {
  61      ...
  62    } elsif ($form->{"sum"} > 0) {
  63      ...
  64    } else {
  65      ...
  66    }
  67
  68    do {
  69      ...
  70    } while ($a > 0);
  71
  72 6. Parameter von Funktionsaufrufen müssen mit runden Klammern versehen
  73    werden.
  74
  75    Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss
  76    selber darauf achten!
  77
  78    Beispiel:
  79
  80    debug("Konnte Datei nicht oeffnen.\n");
  81
  82 7. Verschiedene Klammern
  83
  84   7.1 Aufeinander folgende runde Klammern sollten nicht durch Leerzeichen
  85       abgesetzt werden.
  86       Perltidy: -pt=2
  87       Beispiel:
  88
  89       if (($form->{"debug"} == 1) && (($form->{"sum"} - 100) < 0)) {
  90         ...
  91       }
  92
  93   7.2 Nach und vor eckigen Klammern sollten keine Leerzeichen stehen.
  94       Perltidy: -sbt=2
  95       Beispiel:
  96
  97       $array[$i + 1] = 4;
  98
  99   7.3 Nach und vor geschweiften Klammern sollten keine Leerzeichen stehen,
 100       es sei denn, sie sind verschachtelt.
 101       Beispiel:
 102
 103       $form->{"sum"} += $form->{"row_${i}"};
 104
 105       $form->{ $form->{"index"} } += 1;
 106
 107   7.4 Nach und vor geschweiften Klammern, die Codeblöcke beschränken,
 108       sollten Leerzeichen stehen, wenn sich der Codeblock über nur eine
 109       Zeile erstreckt.
 110       Perltidy: -bbt=0
 111       Beispiel:
 112
 113       map({ $form->{"sum"} += $form->{"row_$_"}; } (1..$rowcount));
 114       $form->{ $row + 1 } = 5;
 115
 116 8. Mehrzeilige Befehle
 117
 118   8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen
 119       aufgeteilt, so müssen diese bis zu der Spalte eingerückt werden,
 120       in der die ersten Funktionsparameter in der ersten Zeile stehen.
 121       Perltidy: -lp -vt=1 -vtc=1
 122       Beispiel:
 123
 124       $sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
 125                            $form->{"some_col_value"});
 126
 127   8.2 Wird ein Befehl auf einer neuen Zeile forgesetzt, so ist ab der
 128       zweiten Zeile zusätzlich zwei Leerzeichen einzurücken.
 129       Perltidy: -ci=2
 130       Beispiel:
 131
 132       my $rowcount =
 133         $form->{"row_$i"} ? $i : $form->{"rowcount"} - $form->{"rowbase"};
 134
 135 9. Kommentare
 136
 137   9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der
 138       Code eingerückt sein.
 139       Perltidy: -ibc
 140
 141   9.2 Seitliche hängende Kommentare sollten einheitlich formatiert werden.
 142       Perltidy: -hsc
 143
 144 10. Hash-Keys sind, sofern es sich um Zeichenketten und nicht um
 145     Nummern handelt, in Anführungszeichen zu setzen.
 146
 147     Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss
 148     selber darauf achten!
 149
 150     Beispiele:
 151
 152     $form->{"sum"} = 0;
 153     $form->{"row_$i"} = $form->{"row_$i"} - 5;
 154     $some_hash{42} = 54;
 155
 156 11. Die Maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen <= 79
 157     helfen, weil sie dann im Textmodus / per SSH deutlich besser lesbar
 158     sind. Oft genug ist es aber nicht möglich oder nur unter großen
 159     Verrenkungen, diese Vorgabe einzuhalten.
 160
 161     Zeilen sollten nicht länger als 79 Zeichen sein.
 162     Perltidy: -l=79
 163
 164 --------------------------------------------------------------------------
 165
 166 Vollständige Liste aller Optionen, die ich für perltidy benutze. Diese
 167 können in ~/.perltidyrc geschrieben werden:
 168
 169 -syn
 170 -i=2
 171 -nt
 172 -pt=2
 173 -sbt=2
 174 -ci=2
 175 -ibc
 176 -hsc
 177 -noll
 178 -nsts
 179 -nsfs
 180 -asc
 181 -dsm
 182 -aws
 183 -bbc
 184 -bbs
 185 -bbb
 186 -mbl=1
 187 -nsob
 188 -ce
 189 -nbl
 190 -nsbl
 191 -cti=0
 192 -bbt=0
 193 -bar
 194 -l=79
 195 -lp
 196 -vt=1
 197 -vtc=1