kivitendo/doc/programmierstilrichtlinien.txt @ 1ecbe728
| d319704a | Moritz Bunkus | 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->{"path"} eq "bin/mozilla") {
|
||||
...
|
||||
}
|
||||
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
|
||||
| 744e823c | Moritz Bunkus | aufgeteilt, so m?ssen diese bis zu der Spalte einger?ckt werden,
|
||
| d319704a | Moritz Bunkus | 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
|