|
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,
|
|
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.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
1. Es werden keine echten iTabs sondern Leerzeichen verwendet.
|
|
|
|
2. Die Einr?ckung betr?gt zwei Leerzeichen.
|
|
Beispiel:
|
|
|
|
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
|
|
der letzte Befehl.
|
|
Beispiele:
|
|
|
|
sub debug {
|
|
...
|
|
}
|
|
|
|
oder
|
|
|
|
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
|
|
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.
|
|
Beispiele:
|
|
|
|
if ($form->{sum} > 1000) {
|
|
...
|
|
} elsif ($form->{sum} > 0) {
|
|
...
|
|
} else {
|
|
...
|
|
}
|
|
|
|
do {
|
|
...
|
|
} until ($a > 0);
|
|
|
|
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:
|
|
|
|
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)) {
|
|
...
|
|
}
|
|
|
|
$array[$i + 1] = 4;
|
|
$form->{sum} += $form->{"row_$i"};
|
|
$form->{ $form->{index} } += 1;
|
|
|
|
map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;
|
|
|
|
8. Mehrzeilige Befehle
|
|
|
|
8.1 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});
|
|
|
|
8.3 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};
|
|
|
|
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.
|
|
|
|
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;
|
|
|
|
# complicated check
|
|
$found = 1 if //
|
|
}
|
|
|
|
$i = 0 # initialize $i
|
|
$n = $i; # save $i
|
|
$i *= $const; # do something crazy
|
|
$i = $n; # recover $i
|
|
|
|
10. Hashkeys sollten nur in Anf?hrungszeichen stehen, wenn die Interpolation
|
|
gew?nscht ist.
|
|
|
|
Beispiele:
|
|
|
|
$form->{sum} = 0;
|
|
$form->{"row_$i"} = $form->{"row_$i"} - 5;
|
|
$some_hash{42} = 54;
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
$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.
|