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 {
...
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, %myconfig sowie der Inhalt der lx-erp.conf
+ werden derzeit aus dem main package importiert. Alle anderen Konstrukte
+ sollten lexikalisch lokal gehalten werden.
projects / kivitendo-erp.git / blobdiff