|
Lx-Office Style Guide
|
|
---------------------
|
|
|
|
Die folgenden Regeln haben das Ziel, den Code m?glichst gut les- und wartbar
|
|
zu machen. Dazu geh?rt zum Einen, dass der Code einheitlich einger?ckt ist,
|
|
aber auch, dass Mehrdeutigkeit so weit es geht vermieden wird (Stichworte
|
|
"Klammern" oder "Hash-Keys").
|
|
|
|
Diese Regeln sind keine Schikane, sondern erleichtern allen das Leben!
|
|
|
|
Jeder, der einen Patch schickt, sollte sein Script vorher durch perltidy
|
|
laufen lassen. Damit werden einige der nachfolgenden Regeln automatisch
|
|
befolgt, andere hingegen nicht. Dort, wo keine perltidy-Optionen angegeben
|
|
sind, muss der Programmierer selbst f?r die Einhaltung sorgen.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet.
|
|
|
|
2. Die Einr?ckung betr?gt zwei Leerzeichen.
|
|
Beispiel:
|
|
|
|
sub debug {
|
|
print(STDERR "Debugging.\n");
|
|
}
|
|
|
|
3. ?ffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
|
|
der letzte Befehl.
|
|
Beispiele:
|
|
|
|
sub debug {
|
|
...
|
|
}
|
|
|
|
oder
|
|
|
|
if ($form->{item_rows} > 0) {
|
|
...
|
|
}
|
|
|
|
4. Schlie?ende geschweifte Klammern sind so weit einger?ckt wie der Befehl/
|
|
die ?ffnende schlie?ende Klammer, die den Block gestartet hat, und nicht
|
|
auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten.
|
|
|
|
5. Die W?rter "else" "elsif", "while" befinden sich auf der gleichen
|
|
Zeile wie schlie?ende geschweifte Klammern.
|
|
Beispiele:
|
|
|
|
if ($form->{sum} > 1000) {
|
|
...
|
|
} elsif ($form->{sum} > 0) {
|
|
...
|
|
} else {
|
|
...
|
|
}
|
|
|
|
do {
|
|
...
|
|
} while ($a > 0);
|
|
|
|
6. Parameter von Funktionsaufrufen m?ssen mit runden Klammern versehen
|
|
werden. Davon nicht betroffen sind interne perl Funktionen.
|
|
|
|
Beispiel:
|
|
|
|
$main::lxdebug->message("Could not find file.");
|
|
%options = map { $_ => 1 } grep { !/^#/ } @config_file;
|
|
|
|
7. Verschiedene Klammern, Ihre Ausdr?cke und Leerzeichen:
|
|
|
|
Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen
|
|
abgesetzt werden. Logische Klammerungen ebensowenig, Bl?cke schon.
|
|
|
|
|
|
Beispiel:
|
|
|
|
if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
|
|
...
|
|
}
|
|
|
|
$array[$i + 1] = 4;
|
|
$form->{sum} += $form->{"row_$i"};
|
|
$form->{ $form->{index} } += 1;
|
|
|
|
map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;
|
|
|
|
8. Mehrzeilige Befehle
|
|
|
|
8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen
|
|
aufgeteilt, so sollten diese bis zu der Spalte einger?ckt werden,
|
|
in der die ersten Funktionsparameter in der ersten Zeile stehen.
|
|
Beispiel:
|
|
|
|
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
|
|
$form->{some_col_value});
|
|
|
|
8.3 Ein Spezialfall ist der tern?re Oprator "?:", der am besten in einer
|
|
?bersichtlichen Tabellenstruktur organisiert wird.
|
|
|
|
Beispiel:
|
|
|
|
my $rowcount = $form->{"row_$i"} ? $i
|
|
: $form->{oldcount} ? $form->{oldcount} + 1
|
|
: $form->{rowcount} - $form->{rowbase};
|
|
|
|
9. Kommentare
|
|
|
|
9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der
|
|
Code einger?ckt sein.
|
|
9.2 Seitliche h?ngende Kommentare sollten einheitlich formatiert werden.
|
|
|
|
9.3 S?mtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch
|
|
zu verfassen. So wie ich keine Lust habe franz?sischen Quelltext zu lesen,
|
|
sollte auch der Lx-Office Quelltext f?r nicht-Deutschsprachige lesbar sein.
|
|
|
|
Beispiel:
|
|
|
|
my $found = 0;
|
|
while (1) {
|
|
last if $found;
|
|
|
|
# complicated check
|
|
$found = 1 if //
|
|
}
|
|
|
|
$i = 0 # initialize $i
|
|
$n = $i; # save $i
|
|
$i *= $const; # do something crazy
|
|
$i = $n; # recover $i
|
|
|
|
10. Hashkeys sollten nur in Anf?hrungszeichen stehen, wenn die Interpolation
|
|
gew?nscht ist.
|
|
|
|
Beispiele:
|
|
|
|
$form->{sum} = 0;
|
|
$form->{"row_$i"} = $form->{"row_$i"} - 5;
|
|
$some_hash{42} = 54;
|
|
|
|
11. Die Maximale Zeilenl?nge ist nicht bescr?nkt. Zeilenl?ngen <= 79
|
|
helfen unter bestimmten Bedingungen, aber wenn die Lesbarkeit unter
|
|
kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann
|
|
ist Lesbarkeit vorzuziehen.
|
|
|
|
Als Beispiel sei print_options aus bin/mozilla/io.pl angef?hrt.
|
|
|
|
12. Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerw?nscht.
|
|
Sie f?hren zu unn?tigen Whitespace?nderungen die diffs verf?lschen.
|
|
|
|
Emacs und vim haben beide recht einfach Methoden daf?r:
|
|
emacs kennt das Kommande nuke-trailing-whitespace,
|
|
vim macht das gleiche manuell ?ber :%s/\s\+$//e
|
|
|
|
12. Es wird kein perltidy verwendet.
|
|
|
|
In der Vergangenheit wurde versucht perltidy zu verwenden um einen
|
|
einheitlichen Stil zu erlangen, es hat sich aber gezeigt, dass Perltidys
|
|
sehr eigenwilliges Verhaltes was Zeilenumbr?che angeht oftmals gut
|
|
formatierten Code zerst?rt. F?r den Interessierten, hier sind die perltidy
|
|
Optionen die grob den beschriebenen Richtlinien entsprechen.
|
|
|
|
-syn
|
|
-i=2
|
|
-nt
|
|
-pt=2
|
|
-sbt=2
|
|
-ci=2
|
|
-ibc
|
|
-hsc
|
|
-noll
|
|
-nsts
|
|
-nsfs
|
|
-asc
|
|
-dsm
|
|
-aws
|
|
-bbc
|
|
-bbs
|
|
-bbb
|
|
-mbl=1
|
|
-nsob
|
|
-ce
|
|
-nbl
|
|
-nsbl
|
|
-cti=0
|
|
-bbt=0
|
|
-bar
|
|
-l=79
|
|
-lp
|
|
-vt=1
|
|
-vtc=1
|