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!
-Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen.
-Einige der Regeln lassen sich automatisch überprüfen, andere nicht.
+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.
+1. Es werden keine echten iTabs sondern Leerzeichen verwendet.
-2. Die Einrückung beträgt zwei Leerzeichen.
+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.
Beispiele:
...
}
-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.
-5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen
- Zeile wie schließende geschweifte Klammern.
+5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen
+ Zeile wie schließende geschweifte Klammern.
Beispiele:
if ($form->{sum} > 1000) {
do {
...
- } while ($a > 0);
+ } until ($a > 0);
-6. Parameter von Funktionsaufrufen müssen mit runden Klammern versehen
- werden. Davon nicht betroffen sind interne perl Funktionen.
+6. 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;
-7. Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:
+7. Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:
Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen
- abgesetzt werden. Logische Klammerungen ebensowenig, Blöcke schon.
+ abgesetzt werden. Logische Klammerungen ebensowenig, Blöcke schon.
Beispiel:
8. Mehrzeilige Befehle
8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen
- aufgeteilt, so sollten 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.
Beispiel:
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
$form->{some_col_value});
- 8.3 Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer
- übersichtlichen Tabellenstruktur organisiert wird.
+ 8.3 Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer
+ übersichtlichen Tabellenstruktur organisiert wird.
Beispiel:
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.
+ 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.
+ 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:
$i *= $const; # do something crazy
$i = $n; # recover $i
-10. Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation
- gewünscht ist.
+10. Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation
+ gewünscht ist.
Beispiele:
$form->{"row_$i"} = $form->{"row_$i"} - 5;
$some_hash{42} = 54;
-11. Die maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen <= 79
+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.
- Als Beispiel sei print_options aus bin/mozilla/io.pl angeführt.
+ 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.
+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 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
+ vim macht das gleiche manuell über :%s/\s\+$//e, mit
:au BufWritePre * :%s/\s\+$//e
wird das an speichern gebunden.
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
+ 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
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
+ 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.
+ meisten Fällen auch vom Repository zurückgewiesen.
+
+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.
projects / kivitendo-erp.git / blobdiff