Revision 8cc37098
Von Sven Schöling vor mehr als 15 Jahren hinzugefügt
| doc/programmierstilrichtlinien.txt | ||
|---|---|---|
| 8 | 8 |
|
| 9 | 9 |
Diese Regeln sind keine Schikane, sondern erleichtern allen das Leben! |
| 10 | 10 |
|
| 11 |
Zum einfachen Formartieren von Perl-Scripten gibt es das Tool "perltidy", |
|
| 12 |
das man weitgehend konfigurieren kann. Bei fast allen nachfolgenden Punkten |
|
| 13 |
sind die dazugeh?rigen perltidy-Optionen angegeben. perltidy ist bei den |
|
| 14 |
meisten Linux-Distributionen enthalten und kann ansonten unter |
|
| 15 |
http://perltidy.sourceforge.net heruntergeladen werden. |
|
| 16 |
|
|
| 17 | 11 |
Jeder, der einen Patch schickt, sollte sein Script vorher durch perltidy |
| 18 | 12 |
laufen lassen. Damit werden einige der nachfolgenden Regeln automatisch |
| 19 | 13 |
befolgt, andere hingegen nicht. Dort, wo keine perltidy-Optionen angegeben |
| ... | ... | |
| 22 | 16 |
-------------------------------------------------------------------------- |
| 23 | 17 |
|
| 24 | 18 |
1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet. |
| 25 |
Perltidy: -nt |
|
| 26 | 19 |
|
| 27 | 20 |
2. Die Einr?ckung betr?gt zwei Leerzeichen. |
| 28 |
Perltidy: -i=2 |
|
| 29 | 21 |
Beispiel: |
| 30 | 22 |
|
| 31 | 23 |
sub debug {
|
| ... | ... | |
| 34 | 26 |
|
| 35 | 27 |
3. ?ffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie |
| 36 | 28 |
der letzte Befehl. |
| 37 |
Perltidy: -nbl -nsbl -bar |
|
| 38 | 29 |
Beispiele: |
| 39 | 30 |
|
| 40 | 31 |
sub debug {
|
| 41 |
... |
|
| 32 |
...
|
|
| 42 | 33 |
} |
| 43 | 34 |
|
| 44 | 35 |
oder |
| ... | ... | |
| 50 | 41 |
4. Schlie?ende geschweifte Klammern sind so weit einger?ckt wie der Befehl/ |
| 51 | 42 |
die ?ffnende schlie?ende Klammer, die den Block gestartet hat, und nicht |
| 52 | 43 |
auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten. |
| 53 |
Perltidy: macht's automatisch |
|
| 54 | 44 |
|
| 55 | 45 |
5. Die W?rter "else" "elsif", "while" befinden sich auf der gleichen |
| 56 | 46 |
Zeile wie schlie?ende geschweifte Klammern. |
| 57 |
Perltidy: -ce |
|
| 58 | 47 |
Beispiele: |
| 59 | 48 |
|
| 60 |
if ($form->{"sum"} > 1000) {
|
|
| 49 |
if ($form->{sum} > 1000) {
|
|
| 61 | 50 |
... |
| 62 |
} elsif ($form->{"sum"} > 0) {
|
|
| 51 |
} elsif ($form->{sum} > 0) {
|
|
| 63 | 52 |
... |
| 64 | 53 |
} else {
|
| 65 | 54 |
... |
| ... | ... | |
| 70 | 59 |
} while ($a > 0); |
| 71 | 60 |
|
| 72 | 61 |
6. Parameter von Funktionsaufrufen m?ssen mit runden Klammern versehen |
| 73 |
werden. |
|
| 74 |
|
|
| 75 |
Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss |
|
| 76 |
selber darauf achten! |
|
| 62 |
werden. Davon nicht betroffen sind interne perl Funktionen. |
|
| 77 | 63 |
|
| 78 | 64 |
Beispiel: |
| 79 | 65 |
|
| 80 |
debug("Konnte Datei nicht oeffnen.\n");
|
|
| 66 |
$main::lxdebug->message("Could not find file.");
|
|
| 67 |
%options = map { $_ => 1 } grep { !/^#/ } @config_file;
|
|
| 81 | 68 |
|
| 82 |
7. Verschiedene Klammern |
|
| 69 |
7. Verschiedene Klammern, Ihre Ausdr?cke und Leerzeichen:
|
|
| 83 | 70 |
|
| 84 |
7.1 Aufeinander folgende runde Klammern sollten nicht durch Leerzeichen |
|
| 85 |
abgesetzt werden. |
|
| 86 |
Perltidy: -pt=2 |
|
| 87 |
Beispiel: |
|
| 71 |
Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen |
|
| 72 |
abgesetzt werden. Logische Klammerungen ebensowenig, Bl?cke schon. |
|
| 88 | 73 |
|
| 89 |
if (($form->{"debug"} == 1) && (($form->{"sum"} - 100) < 0)) {
|
|
| 90 |
... |
|
| 91 |
} |
|
| 92 | 74 |
|
| 93 |
7.2 Nach und vor eckigen Klammern sollten keine Leerzeichen stehen. |
|
| 94 |
Perltidy: -sbt=2 |
|
| 95 |
Beispiel: |
|
| 75 |
Beispiel: |
|
| 96 | 76 |
|
| 97 |
$array[$i + 1] = 4; |
|
| 98 |
|
|
| 99 |
7.3 Nach und vor geschweiften Klammern sollten keine Leerzeichen stehen, |
|
| 100 |
es sei denn, sie sind verschachtelt. |
|
| 101 |
Beispiel: |
|
| 102 |
|
|
| 103 |
$form->{"sum"} += $form->{"row_${i}"};
|
|
| 77 |
if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
|
|
| 78 |
... |
|
| 79 |
} |
|
| 104 | 80 |
|
| 105 |
$form->{ $form->{"index"} } += 1;
|
|
| 81 |
$array[$i + 1] = 4; |
|
| 82 |
$form->{sum} += $form->{"row_$i"};
|
|
| 83 |
$form->{ $form->{index} } += 1;
|
|
| 106 | 84 |
|
| 107 |
7.4 Nach und vor geschweiften Klammern, die Codebl?cke beschr?nken, |
|
| 108 |
sollten Leerzeichen stehen, wenn sich der Codeblock ?ber nur eine |
|
| 109 |
Zeile erstreckt. |
|
| 110 |
Perltidy: -bbt=0 |
|
| 111 |
Beispiel: |
|
| 112 |
|
|
| 113 |
map({ $form->{"sum"} += $form->{"row_$_"}; } (1..$rowcount));
|
|
| 114 |
$form->{ $row + 1 } = 5;
|
|
| 85 |
map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;
|
|
| 115 | 86 |
|
| 116 | 87 |
8. Mehrzeilige Befehle |
| 117 | 88 |
|
| 118 | 89 |
8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen |
| 119 |
aufgeteilt, so m?ssen diese bis zu der Spalte einger?ckt werden,
|
|
| 90 |
aufgeteilt, so sollten diese bis zu der Spalte einger?ckt werden,
|
|
| 120 | 91 |
in der die ersten Funktionsparameter in der ersten Zeile stehen. |
| 121 |
Perltidy: -lp -vt=1 -vtc=1 |
|
| 122 | 92 |
Beispiel: |
| 123 | 93 |
|
| 124 | 94 |
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
|
| 125 |
$form->{"some_col_value"});
|
|
| 95 |
$form->{some_col_value});
|
|
| 96 |
|
|
| 97 |
8.3 Ein Spezialfall ist der tern?re Oprator "?:", der am besten in einer |
|
| 98 |
?bersichtlichen Tabellenstruktur organisiert wird. |
|
| 126 | 99 |
|
| 127 |
8.2 Wird ein Befehl auf einer neuen Zeile forgesetzt, so ist ab der |
|
| 128 |
zweiten Zeile zus?tzlich zwei Leerzeichen einzur?cken. |
|
| 129 |
Perltidy: -ci=2 |
|
| 130 | 100 |
Beispiel: |
| 131 | 101 |
|
| 132 |
my $rowcount = |
|
| 133 |
$form->{"row_$i"} ? $i : $form->{"rowcount"} - $form->{"rowbase"};
|
|
| 102 |
my $rowcount = $form->{"row_$i"} ? $i
|
|
| 103 |
: $form->{oldcount} ? $form->{oldcount} + 1
|
|
| 104 |
: $form->{rowcount} - $form->{rowbase};
|
|
| 134 | 105 |
|
| 135 | 106 |
9. Kommentare |
| 136 | 107 |
|
| 137 | 108 |
9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der |
| 138 | 109 |
Code einger?ckt sein. |
| 139 |
Perltidy: -ibc |
|
| 140 |
|
|
| 141 | 110 |
9.2 Seitliche h?ngende Kommentare sollten einheitlich formatiert werden. |
| 142 |
Perltidy: -hsc |
|
| 143 | 111 |
|
| 144 |
10. Hash-Keys sind, sofern es sich um Zeichenketten und nicht um |
|
| 145 |
Nummern handelt, in Anf?hrungszeichen zu setzen. |
|
| 112 |
9.3 S?mtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch |
|
| 113 |
zu verfassen. So wie ich keine Lust habe franz?sischen Quelltext zu lesen, |
|
| 114 |
sollte auch der Lx-Office Quelltext f?r nicht-Deutschsprachige lesbar sein. |
|
| 115 |
|
|
| 116 |
Beispiel: |
|
| 117 |
|
|
| 118 |
my $found = 0; |
|
| 119 |
while (1) {
|
|
| 120 |
last if $found; |
|
| 146 | 121 |
|
| 147 |
Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss |
|
| 148 |
selber darauf achten! |
|
| 122 |
# complicated check |
|
| 123 |
$found = 1 if // |
|
| 124 |
} |
|
| 125 |
|
|
| 126 |
$i = 0 # initialize $i |
|
| 127 |
$n = $i; # save $i |
|
| 128 |
$i *= $const; # do something crazy |
|
| 129 |
$i = $n; # recover $i |
|
| 130 |
|
|
| 131 |
10. Hashkeys sollten nur in Anf?hrungszeichen stehen, wenn die Interpolation |
|
| 132 |
gew?nscht ist. |
|
| 149 | 133 |
|
| 150 | 134 |
Beispiele: |
| 151 | 135 |
|
| 152 |
$form->{"sum"} = 0;
|
|
| 136 |
$form->{sum} = 0;
|
|
| 153 | 137 |
$form->{"row_$i"} = $form->{"row_$i"} - 5;
|
| 154 |
$some_hash{42} = 54;
|
|
| 138 |
$some_hash{42} = 54;
|
|
| 155 | 139 |
|
| 156 | 140 |
11. Die Maximale Zeilenl?nge ist nicht bescr?nkt. Zeilenl?ngen <= 79 |
| 157 |
helfen, weil sie dann im Textmodus / per SSH deutlich besser lesbar
|
|
| 158 |
sind. Oft genug ist es aber nicht m?glich oder nur unter gro?en
|
|
| 159 |
Verrenkungen, diese Vorgabe einzuhalten.
|
|
| 141 |
helfen unter bestimmten Bedingungen, aber wenn die Lesbarkeit unter
|
|
| 142 |
kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann
|
|
| 143 |
ist Lesbarkeit vorzuziehen.
|
|
| 160 | 144 |
|
| 161 |
Zeilen sollten nicht l?nger als 79 Zeichen sein. |
|
| 162 |
Perltidy: -l=79 |
|
| 145 |
Als Beispiel sei print_options aus bin/mozilla/io.pl angef?hrt. |
|
| 163 | 146 |
|
| 164 |
-------------------------------------------------------------------------- |
|
| 147 |
12. Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerw?nscht. |
|
| 148 |
Sie f?hren zu unn?tigen Whitespace?nderungen die diffs verf?lschen. |
|
| 149 |
|
|
| 150 |
Emacs und vim haben beide recht einfach Methoden daf?r: |
|
| 151 |
emacs kennt das Kommande nuke-trailing-whitespace, |
|
| 152 |
vim macht das gleiche manuell ?ber :%s/\s\+$//e |
|
| 153 |
|
|
| 154 |
12. Es wird kein perltidy verwendet. |
|
| 165 | 155 |
|
| 166 |
Vollst?ndige Liste aller Optionen, die ich f?r perltidy benutze. Diese |
|
| 167 |
k?nnen in ~/.perltidyrc geschrieben werden: |
|
| 156 |
In der Vergangenheit wurde versucht perltidy zu verwenden um einen |
|
| 157 |
einheitlichen Stil zu erlangen, es hat sich aber gezeigt, dass Perltidys |
|
| 158 |
sehr eigenwilliges Verhaltes was Zeilenumbr?che angeht oftmals gut |
|
| 159 |
formatierten Code zerst?rt. F?r den Interessierten, hier sind die perltidy |
|
| 160 |
Optionen die grob den beschriebenen Richtlinien entsprechen. |
|
| 168 | 161 |
|
| 169 | 162 |
-syn |
| 170 | 163 |
-i=2 |
Auch abrufbar als: Unified diff
Programmierrichtlinien etwas aktualisiert.