|
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!
|
|
|
|
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.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet.
|
|
Perltidy: -nt
|
|
|
|
2. Die Einr?ckung betr?gt zwei Leerzeichen.
|
|
Perltidy: -i=2
|
|
Beispiel:
|
|
|
|
sub debug {
|
|
print(STDERR "Debugging.\n");
|
|
}
|
|
|
|
3. ?ffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
|
|
der letzte Befehl.
|
|
Perltidy: -nbl -nsbl -bar
|
|
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.
|
|
Perltidy: macht's automatisch
|
|
|
|
5. Die W?rter "else" "elsif", "while" befinden sich auf der gleichen
|
|
Zeile wie schlie?ende geschweifte Klammern.
|
|
Perltidy: -ce
|
|
Beispiele:
|
|
|
|
if ($form->{"sum"} > 1000) {
|
|
...
|
|
} elsif ($form->{"sum"} > 0) {
|
|
...
|
|
} else {
|
|
...
|
|
}
|
|
|
|
do {
|
|
...
|
|
} while ($a > 0);
|
|
|
|
6. Parameter von Funktionsaufrufen m?ssen mit runden Klammern versehen
|
|
werden.
|
|
|
|
Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss
|
|
selber darauf achten!
|
|
|
|
Beispiel:
|
|
|
|
debug("Konnte Datei nicht oeffnen.\n");
|
|
|
|
7. Verschiedene Klammern
|
|
|
|
7.1 Aufeinander folgende runde Klammern sollten nicht durch Leerzeichen
|
|
abgesetzt werden.
|
|
Perltidy: -pt=2
|
|
Beispiel:
|
|
|
|
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:
|
|
|
|
$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;
|
|
|
|
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,
|
|
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"});
|
|
|
|
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"};
|
|
|
|
9. Kommentare
|
|
|
|
9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der
|
|
Code einger?ckt sein.
|
|
Perltidy: -ibc
|
|
|
|
9.2 Seitliche h?ngende Kommentare sollten einheitlich formatiert werden.
|
|
Perltidy: -hsc
|
|
|
|
10. Hash-Keys sind, sofern es sich um Zeichenketten und nicht um
|
|
Nummern handelt, in Anf?hrungszeichen zu setzen.
|
|
|
|
Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss
|
|
selber darauf achten!
|
|
|
|
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, 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.
|
|
|
|
Zeilen sollten nicht l?nger als 79 Zeichen sein.
|
|
Perltidy: -l=79
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
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
|