kivitendo/doc/programmierstilrichtlinien.txt @ 37c67888
| 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!
|
||||
| ec63079e | Sven Schöling | Jeder, der einen Patch schickt, sollte seinen Code vorher ?berpr?fen.
|
||
Einige der Regeln lassen sich automatisch ?berpr?fen, andere nicht.
|
||||
| d319704a | Moritz Bunkus | |||
--------------------------------------------------------------------------
|
||||
| 2dacd279 | Sven Schöling | 1. Es werden keine echten iTabs sondern Leerzeichen verwendet.
|
||
| d319704a | Moritz Bunkus | |||
2. Die Einr?ckung betr?gt zwei Leerzeichen.
|
||||
Beispiel:
|
||||
| 2dacd279 | Sven Schöling | foreach my $row (@data) {
|
||
if ($flag) {
|
||||
# do something with $row
|
||||
}
|
||||
if ($use_modules) {
|
||||
$row->{modules} = MODULE->retrieve(
|
||||
id => $row->{id},
|
||||
date => $use_now ? localtime() : $row->{time},
|
||||
);
|
||||
}
|
||||
$report->add($row);
|
||||
| d319704a | Moritz Bunkus | }
|
||
| 2dacd279 | Sven Schöling | |||
| d319704a | Moritz Bunkus | 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 {
|
||||
...
|
||||
| 2dacd279 | Sven Schöling | } until ($a > 0);
|
||
| d319704a | Moritz Bunkus | |||
6. Parameter von Funktionsaufrufen m?ssen mit runden Klammern versehen
|
||||
| 2dacd279 | Sven Schöling | werden. Davon nicht betroffen sind interne perl Funktionen,
|
||
und grep ?hnliche Operatoren.
|
||||
| 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 | |||
| ec63079e | Sven Schöling | 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.
|
||||
| ec63079e | Sven Schöling | Emacs und vim haben beide recht einfache Methoden daf?r:
|
||
| 8cc37098 | Sven Schöling | emacs kennt das Kommande nuke-trailing-whitespace,
|
||
| ec63079e | Sven Schöling | vim macht das gleiche manuell ?ber :%s/\s\+$//e, mit
|
||
:au BufWritePre * :%s/\s\+$//e
|
||||
wird das an speichern gebunden.
|
||||
| 8cc37098 | Sven Schöling | |||
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
|
||||
| ec63079e | Sven Schöling | formatierten Code zerst?rt. F?r den Interessierten sind hier 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
|
||||
13. STDERR ist tabu. Unkonditionale Debugmeldungen auch.
|
||||
Lx-Office bietet mit dem LXDebug Modul einen brauchbaren Trace/Debug
|
||||
Mechanismus, es gibt also keinen Grund nach STDERR zu schreiben.
|
||||
Die LXDebug Methode "message" nimmt als ersten Paramter au?erdem eine
|
||||
Flagmaske, f?r die die Meldung angezeigt wird, wobei "0" immer angezeigt
|
||||
wird. Sollte Meldungen sollten nicht eingecheckt werden, und werden in den
|
||||
meisten F?llen auch vom Repository zur?ckgewiesen.
|
||||
| 2dacd279 | Sven Schöling | |||
14. Alle neuen Module m?ssen use strict verwenden.
|
||||
$form, $auth, $locale, $lxdebug, %myconfig sowie der Inhalt der lx-erp.conf
|
||||
werden derzeit aus dem main package importiert. Alle anderen Konstrukte
|
||||
sollten lexikalisch lokal gehalten werden.
|