X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fprogrammierstilrichtlinien.txt;h=4b8b20122cffaf857f26f8803b18ee2cb1562fc0;hb=70c755e0fc1e8b8d6a14811037d8fa98dddab0f7;hp=aec999fed81a1664a9d259fd2d1b1cc0bfc354ad;hpb=744e823c3bad065c1b7ad1e40535b86747549324;p=kivitendo-erp.git diff --git a/doc/programmierstilrichtlinien.txt b/doc/programmierstilrichtlinien.txt index aec999fed..4b8b20122 100644 --- a/doc/programmierstilrichtlinien.txt +++ b/doc/programmierstilrichtlinien.txt @@ -1,65 +1,64 @@ 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, +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! -Zum einfachen Formartieren von Perl-Scripten gibt es das Tool "perltidy", -das man weitgehend konfigurieren kann. Bei fast allen nachfolgenden Punkten -sind die dazugehörigen perltidy-Optionen angegeben. perltidy ist bei den -meisten Linux-Distributionen enthalten und kann ansonten unter -http://perltidy.sourceforge.net heruntergeladen werden. - -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. +Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen. +Einige der Regeln lassen sich automatisch überprüfen, andere nicht. -------------------------------------------------------------------------- -1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet. - Perltidy: -nt +1. Es werden keine echten iTabs sondern Leerzeichen verwendet. -2. Die Einrückung beträgt zwei Leerzeichen. - Perltidy: -i=2 +2. Die Einrückung beträgt zwei Leerzeichen. Beispiel: - sub debug { - print(STDERR "Debugging.\n"); + 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); } -3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie + +3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie der letzte Befehl. - Perltidy: -nbl -nsbl -bar Beispiele: sub debug { - ... + ... } oder - if ($form->{"path"} eq "bin/mozilla") { + 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 +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. - Perltidy: macht's automatisch -5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen - Zeile wie schließende geschweifte Klammern. - Perltidy: -ce +5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen + Zeile wie schließende geschweifte Klammern. Beispiele: - if ($form->{"sum"} > 1000) { + if ($form->{sum} > 1000) { ... - } elsif ($form->{"sum"} > 0) { + } elsif ($form->{sum} > 0) { ... } else { ... @@ -67,131 +66,128 @@ sind, muss der Programmierer selbst f do { ... - } while ($a > 0); - -6. Parameter von Funktionsaufrufen müssen mit runden Klammern versehen - werden. + } until ($a > 0); - Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss - selber darauf achten! +6. Parameter von Funktionsaufrufen müssen mit runden Klammern versehen + werden. Davon nicht betroffen sind interne perl Funktionen, + und grep ähnliche Operatoren. Beispiel: - debug("Konnte Datei nicht oeffnen.\n"); + $main::lxdebug->message("Could not find file."); + %options = map { $_ => 1 } grep { !/^#/ } @config_file; -7. Verschiedene Klammern +7. Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen: - 7.1 Aufeinander folgende runde Klammern sollten nicht durch Leerzeichen - abgesetzt werden. - Perltidy: -pt=2 - Beispiel: + Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen + abgesetzt werden. Logische Klammerungen ebensowenig, Blöcke schon. - if (($form->{"debug"} == 1) && (($form->{"sum"} - 100) < 0)) { - ... - } - - 7.2 Nach und vor eckigen Klammern sollten keine Leerzeichen stehen. - Perltidy: -sbt=2 - Beispiel: - - $array[$i + 1] = 4; - 7.3 Nach und vor geschweiften Klammern sollten keine Leerzeichen stehen, - es sei denn, sie sind verschachtelt. - Beispiel: + Beispiel: - $form->{"sum"} += $form->{"row_${i}"}; + if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) { + ... + } - $form->{ $form->{"index"} } += 1; + $array[$i + 1] = 4; + $form->{sum} += $form->{"row_$i"}; + $form->{ $form->{index} } += 1; - 7.4 Nach und vor geschweiften Klammern, die Codeblöcke beschränken, - sollten Leerzeichen stehen, wenn sich der Codeblock über nur eine - Zeile erstreckt. - Perltidy: -bbt=0 - Beispiel: - - map({ $form->{"sum"} += $form->{"row_$_"}; } (1..$rowcount)); - $form->{ $row + 1 } = 5; + map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount; 8. Mehrzeilige Befehle 8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen - aufgeteilt, so müssen diese bis zu der Spalte eingerückt werden, + aufgeteilt, so sollten diese bis zu der Spalte eingerückt werden, in der die ersten Funktionsparameter in der ersten Zeile stehen. - Perltidy: -lp -vt=1 -vtc=1 Beispiel: $sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?", - $form->{"some_col_value"}); + $form->{some_col_value}); + + 8.3 Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer + übersichtlichen Tabellenstruktur organisiert wird. - 8.2 Wird ein Befehl auf einer neuen Zeile forgesetzt, so ist ab der - zweiten Zeile zusätzlich zwei Leerzeichen einzurücken. - Perltidy: -ci=2 Beispiel: - my $rowcount = - $form->{"row_$i"} ? $i : $form->{"rowcount"} - $form->{"rowbase"}; + 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. - Perltidy: -ibc + 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; - 9.2 Seitliche hängende Kommentare sollten einheitlich formatiert werden. - Perltidy: -hsc + # complicated check + $found = 1 if // + } -10. Hash-Keys sind, sofern es sich um Zeichenketten und nicht um - Nummern handelt, in Anführungszeichen zu setzen. + $i = 0 # initialize $i + $n = $i; # save $i + $i *= $const; # do something crazy + $i = $n; # recover $i - Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss - selber darauf achten! +10. Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation + gewünscht ist. Beispiele: - $form->{"sum"} = 0; + $form->{sum} = 0; $form->{"row_$i"} = $form->{"row_$i"} - 5; - $some_hash{42} = 54; + $some_hash{42} = 54; -11. Die Maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen <= 79 - helfen, weil sie dann im Textmodus / per SSH deutlich besser lesbar - sind. Oft genug ist es aber nicht möglich oder nur unter großen - Verrenkungen, diese Vorgabe einzuhalten. +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. - Zeilen sollten nicht länger als 79 Zeichen sein. - Perltidy: -l=79 + 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 einfache Methoden dafür: + emacs kennt das Kommande nuke-trailing-whitespace, + vim macht das gleiche manuell über :%s/\s\+$//e, mit + :au BufWritePre * :%s/\s\+$//e + wird das an speichern gebunden. + +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 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. + +14. Alle neuen Module müssen use strict verwenden. -Vollständige Liste aller Optionen, die ich für perltidy benutze. Diese -können in ~/.perltidyrc geschrieben werden: - --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 + $form, $auth, $locale, $lxdebug und %myconfig werden derzeit aus dem main + package importiert. Alle anderen Konstrukte sollten lexikalisch lokal + gehalten werden.