kivitendo/doc/programmierstilrichtlinien.txt @ 9434c14a
| d319704a | Moritz Bunkus | Lx-Office Style Guide
|
||
---------------------
|
||||
| 4c24a5f4 | Sven Schöling | 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,
|
||||
| d319704a | Moritz Bunkus | 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!
|
||||
| 4c24a5f4 | 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 | |||
| 4c24a5f4 | Sven Schöling | 2. Die Einrückung beträgt zwei Leerzeichen.
|
||
| d319704a | Moritz Bunkus | 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 | |||
| 4c24a5f4 | Sven Schöling | 3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
|
||
| d319704a | Moritz Bunkus | 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 | ...
|
||
}
|
||||
| 4c24a5f4 | Sven Schöling | 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
|
||||
| d319704a | Moritz Bunkus | auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten.
|
||
| 4c24a5f4 | Sven Schöling | 5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen
|
||
Zeile wie schließende geschweifte Klammern.
|
||||
| d319704a | Moritz Bunkus | 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 | |||
| 4c24a5f4 | Sven Schöling | 6. Parameter von Funktionsaufrufen müssen mit runden Klammern versehen
|
||
| 2dacd279 | Sven Schöling | werden. Davon nicht betroffen sind interne perl Funktionen,
|
||
| 4c24a5f4 | Sven Schöling | 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 | |||
| 4c24a5f4 | 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
|
||
| 4c24a5f4 | Sven Schöling | 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
|
||||
| 4c24a5f4 | 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});
|
||
| 4c24a5f4 | Sven Schöling | 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
|
||||
| 4c24a5f4 | Sven Schöling | Code eingerückt sein.
|
||
9.2 Seitliche hängende Kommentare sollten einheitlich formatiert werden.
|
||||
| d319704a | Moritz Bunkus | |||
| 4c24a5f4 | 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.
|
||||
| 8cc37098 | Sven Schöling | |||
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
|
||||
| 4c24a5f4 | Sven Schöling | 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 | |||
| 4c24a5f4 | 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 | |||
| 4c24a5f4 | Sven Schöling | Als Beispiel sei print_options aus bin/mozilla/io.pl angeführt.
|
||
| d319704a | Moritz Bunkus | |||
| 4c24a5f4 | 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.
|
||||
| 8cc37098 | Sven Schöling | |||
| 4c24a5f4 | Sven Schöling | Emacs und vim haben beide recht einfache Methoden dafür:
|
||
| 8cc37098 | Sven Schöling | emacs kennt das Kommande nuke-trailing-whitespace,
|
||
| 4c24a5f4 | Sven Schöling | vim macht das gleiche manuell über :%s/\s\+$//e, mit
|
||
| ec63079e | Sven Schöling | :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
|
||||
| 4c24a5f4 | Sven Schöling | sehr eigenwilliges Verhaltes was Zeilenumbrüche angeht oftmals gut
|
||
formatierten Code zerstört. Für den Interessierten sind hier die perltidy
|
||||
| ec63079e | Sven Schöling | 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.
|
||||
| 4c24a5f4 | Sven Schöling | Die LXDebug Methode "message" nimmt als ersten Paramter außerdem eine
|
||
Flagmaske, für die die Meldung angezeigt wird, wobei "0" immer angezeigt
|
||||
| ec63079e | Sven Schöling | wird. Sollte Meldungen sollten nicht eingecheckt werden, und werden in den
|
||
| 4c24a5f4 | Sven Schöling | meisten Fällen auch vom Repository zurückgewiesen.
|
||
| 2dacd279 | Sven Schöling | |||
| 4c24a5f4 | Sven Schöling | 14. Alle neuen Module müssen use strict verwenden.
|
||
| 2dacd279 | Sven Schöling | |||
$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.
|