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").
9 Diese Regeln sind keine Schikane, sondern erleichtern allen das Leben!
11 Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen.
12 Einige der Regeln lassen sich automatisch überprüfen, andere nicht.
14 --------------------------------------------------------------------------
16 1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet.
18 2. Die Einrückung beträgt zwei Leerzeichen.
22 print(STDERR "Debugging.\n");
25 3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
35 if ($form->{item_rows} > 0) {
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.
43 5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen
44 Zeile wie schließende geschweifte Klammern.
47 if ($form->{sum} > 1000) {
49 } elsif ($form->{sum} > 0) {
59 6. Parameter von Funktionsaufrufen müssen mit runden Klammern versehen
60 werden. Davon nicht betroffen sind interne perl Funktionen.
64 $main::lxdebug->message("Could not find file.");
65 %options = map { $_ => 1 } grep { !/^#/ } @config_file;
67 7. Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:
69 Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen
70 abgesetzt werden. Logische Klammerungen ebensowenig, Blöcke schon.
75 if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
80 $form->{sum} += $form->{"row_$i"};
81 $form->{ $form->{index} } += 1;
83 map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;
85 8. Mehrzeilige Befehle
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.
92 $sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
93 $form->{some_col_value});
95 8.3 Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer
96 übersichtlichen Tabellenstruktur organisiert wird.
100 my $rowcount = $form->{"row_$i"} ? $i
101 : $form->{oldcount} ? $form->{oldcount} + 1
102 : $form->{rowcount} - $form->{rowbase};
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.
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.
124 $i = 0 # initialize $i
126 $i *= $const; # do something crazy
127 $i = $n; # recover $i
129 10. Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation
135 $form->{"row_$i"} = $form->{"row_$i"} - 5;
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.
143 Als Beispiel sei print_options aus bin/mozilla/io.pl angeführt.
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.
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.
154 12. Es wird kein perltidy verwendet.
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.
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
166 13. STDERR ist tabu. Unkonditionale Debugmeldungen auch.
168 Lx-Office bietet mit dem LXDebug Modul einen brauchbaren Trace/Debug
169 Mechanismus, es gibt also keinen Grund nach STDERR zu schreiben.
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.