X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fhtml%2Fch04s05.html;h=9d3743f079daf0aaa39a4a361072f0fac670c84f;hb=fa78733fbf9b7fdc1c2b255d0eb67e37acdfccea;hp=442f3e05b693220e48f4b9621b10e40573a1634f;hpb=15f021a67aa7e26458a3fbac8efe89ef9c0b0657;p=kivitendo-erp.git diff --git a/doc/html/ch04s05.html b/doc/html/ch04s05.html index 442f3e05b..9d3743f07 100644 --- a/doc/html/ch04s05.html +++ b/doc/html/ch04s05.html @@ -1,18 +1,13 @@
- -- 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 seinen Code vorher überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere - nicht. -
- Es werden keine echten Tabs sondern Leerzeichen verwendet. -
- Die Einrückung beträgt zwei Leerzeichen. Beispiel: -
foreach my $row (@data) { + +4.5. Stil-Richtlinien \ No newline at end of file +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 seinen Code vorher + überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere + nicht.
Es werden keine echten Tabs sondern Leerzeichen + verwendet.
Die Einrückung beträgt zwei Leerzeichen. Beispiel:
foreach my $row (@data) { if ($flag) { # do something with $row } @@ -25,17 +20,18 @@ } $report->add($row); -}Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie der letzte Befehl. Beispiele:
sub debug { +}Ãffnende geschweifte Klammern befinden sich auf der gleichen + Zeile wie der letzte Befehl. Beispiele:
sub debug { ... }oder
if ($form->{item_rows} > 0) { ... -}- 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. -
- Die Wörter "
else
", "elsif
", "while
" befinden sich auf der gleichen - Zeile wie schließende geschweifte Klammern. Beispiele: -if ($form->{sum} > 1000) { +}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.
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) { ... @@ -45,16 +41,12 @@ do { ... -} until ($a > 0);- Parameter von Funktionsaufrufen müssen mit runden Klammern versehen werden. Davon nicht betroffen sind interne Perl-Funktionen, - und grep-ähnliche Operatoren. Beispiel: -
$main::lxdebug->message("Could not find file."); -%options = map { $_ => 1 } grep { !/^#/ } @config_file;- 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)) { +} until ($a > 0);Parameter von Funktionsaufrufen müssen mit runden Klammern + versehen werden. Davon nicht betroffen sind interne Perl-Funktionen, + und grep-ähnliche Operatoren. Beispiel:
$main::lxdebug->message("Could not find file."); +%options = map { $_ => 1 } grep { !/^#/ } @config_file;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)) { ... } @@ -62,23 +54,21 @@ $array[$i + 1] = 4; $form->{sum} += $form->{"row_$i"}; $form->{ $form->{index} } += 1; -map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;- Mehrzeilige Befehle -
- 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});- Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer übersichtlichen Tabellenstruktur organisiert - wird. Beispiel: -
my $rowcount = $form->{"row_$i"} ? $i +map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;Mehrzeilige Befehle
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});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};- Kommentare -
Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der Code eingerückt sein.
Seitliche hängende Kommentare sollten einheitlich formatiert werden.
- 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; + : $form->{rowcount} - $form->{rowbase};Kommentare
Kommentare, die alleine in einer Zeile stehen, sollten + soweit wie der Code eingerückt sein.
Seitliche hängende Kommentare sollten einheitlich + formatiert werden.
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 kivitendo + Quelltext für nicht-Deutschsprachige lesbar sein. + Beispiel:
my $found = 0; while (1) { last if $found; @@ -89,46 +79,42 @@ while (1) { $i = 0 # initialize $i $n = $i; # save $i $i *= $const; # do something crazy -$i = $n; # recover $i- Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation gewünscht ist. Beispiel: -
$form->{sum} = 0; +$i = $n; # recover $iHashkeys sollten nur in Anführungszeichen stehen, wenn die + Interpolation gewünscht ist. Beispiel:
$form->{sum} = 0; $form->{"row_$i"} = $form->{"row_$i"} - 5; -$some_hash{42} = 54;- Die maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen unterhalb von 79 Zeichen 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 die Funktion
print_options
ausbin/mozilla/io.pl
angeführt. -- 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 zur Entfernung von trailing whitespace. 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. -- 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 Verhalten, 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 +$some_hash{42} = 54;Die maximale Zeilenlänge ist nicht beschränkt. Zeilenlängen + unterhalb von 79 Zeichen 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 die Funktion +
print_options
aus +bin/mozilla/io.pl
angeführt.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 zur + Entfernung von trailing whitespace. 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.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 Verhalten, 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- -
STDERR
ist tabu. Unkonditionale Debugmeldungen auch. -- Lx-Office bietet mit dem Modul
LXDebug
einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen - Grund, nachSTDERR
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. Solche Meldungen sollten nicht eingecheckt werden und werden in - den meisten Fällen auch vom Repository zurückgewiesen. -- Alle neuen Module müssen use strict verwenden. -
- -
$form
,$auth
,$locale
,$lxdebug
und -%myconfig
werden derzeit aus dem main package importiert (siehe Globale Variablen. Alle anderen - Konstrukte sollten lexikalisch lokal gehalten werden. -STDERR
ist tabu. Unkonditionale + Debugmeldungen auch.kivitendo bietet mit dem Modul
LXDebug
+ einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen + Grund, nachSTDERR
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. Solche Meldungen sollten nicht eingecheckt werden + und werden in den meisten Fällen auch vom Repository + zurückgewiesen.
Alle neuen Module müssen use strict verwenden.
+ $form
, $auth
,
+ $locale
, $lxdebug
und
+ %myconfig
werden derzeit aus dem main package
+ importiert (siehe Globale Variablen. Alle anderen
+ Konstrukte sollten lexikalisch lokal gehalten werden.