kivitendo/doc/programmierstilrichtlinien.txt @ d14f6a63
| d319704a | Moritz Bunkus | 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 {
|
||||
| 8cc37098 | Sven Schöling | ...
|
||
| d319704a | Moritz Bunkus | }
|
||
oder
|
||||
| d629acd8 | Sven Schöling | if ($form->{item_rows} > 0) {
|
||
| d319704a | Moritz Bunkus | ...
|
||
}
|
||||
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:
|
||||
| 8cc37098 | Sven Schöling | if ($form->{sum} > 1000) {
|
||
| d319704a | Moritz Bunkus | ...
|
||
| 8cc37098 | Sven Schöling | } elsif ($form->{sum} > 0) {
|
||
| d319704a | Moritz Bunkus | ...
|
||
} else {
|
||||
...
|
||||
}
|
||||
do {
|
||||
...
|
||||
} while ($a > 0);
|
||||
6. Parameter von Funktionsaufrufen m?ssen mit runden Klammern versehen
|
||||
| 8cc37098 | Sven Schöling | werden. Davon nicht betroffen sind interne perl Funktionen.
|
||
| d319704a | Moritz Bunkus | |||
Beispiel:
|
||||
| 8cc37098 | Sven Schöling | $main::lxdebug->message("Could not find file.");
|
||
%options = map { $_ => 1 } grep { !/^#/ } @config_file;
|
||||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | 7. Verschiedene Klammern, Ihre Ausdr?cke und Leerzeichen:
|
||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen
|
||
abgesetzt werden. Logische Klammerungen ebensowenig, Bl?cke schon.
|
||||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | Beispiel:
|
||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
|
||
...
|
||||
}
|
||||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | $array[$i + 1] = 4;
|
||
$form->{sum} += $form->{"row_$i"};
|
||||
$form->{ $form->{index} } += 1;
|
||||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;
|
||
| d319704a | Moritz Bunkus | |||
8. Mehrzeilige Befehle
|
||||
8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen
|
||||
| 8cc37098 | Sven Schöling | aufgeteilt, so sollten diese bis zu der Spalte einger?ckt werden,
|
||
| d319704a | Moritz Bunkus | in der die ersten Funktionsparameter in der ersten Zeile stehen.
|
||
Beispiel:
|
||||
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
|
||||
| 8cc37098 | Sven Schöling | $form->{some_col_value});
|
||
8.3 Ein Spezialfall ist der tern?re Oprator "?:", der am besten in einer
|
||||
?bersichtlichen Tabellenstruktur organisiert wird.
|
||||
| d319704a | Moritz Bunkus | |||
Beispiel:
|
||||
| 8cc37098 | Sven Schöling | my $rowcount = $form->{"row_$i"} ? $i
|
||
: $form->{oldcount} ? $form->{oldcount} + 1
|
||||
: $form->{rowcount} - $form->{rowbase};
|
||||
| d319704a | Moritz Bunkus | |||
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.
|
||||
| 8cc37098 | Sven Schöling | 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;
|
||||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | # 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.
|
||||
| d319704a | Moritz Bunkus | |||
Beispiele:
|
||||
| 8cc37098 | Sven Schöling | $form->{sum} = 0;
|
||
| d319704a | Moritz Bunkus | $form->{"row_$i"} = $form->{"row_$i"} - 5;
|
||
| 8cc37098 | Sven Schöling | $some_hash{42} = 54;
|
||
| d319704a | Moritz Bunkus | |||
11. Die Maximale Zeilenl?nge ist nicht bescr?nkt. Zeilenl?ngen <= 79
|
||||
| 8cc37098 | Sven Schöling | helfen unter bestimmten Bedingungen, aber wenn die Lesbarkeit unter
|
||
kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann
|
||||
ist Lesbarkeit vorzuziehen.
|
||||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | Als Beispiel sei print_options aus bin/mozilla/io.pl angef?hrt.
|
||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | 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.
|
||||
| d319704a | Moritz Bunkus | |||
| 8cc37098 | Sven Schöling | 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.
|
||||
| d319704a | Moritz Bunkus | |||
-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
|