Revision 4c24a5f4
Von Sven Schöling vor mehr als 14 Jahren hinzugefügt
| doc/programmierstilrichtlinien.txt | ||
|---|---|---|
| 1 | 1 |
Lx-Office Style Guide |
| 2 | 2 |
--------------------- |
| 3 | 3 |
|
| 4 |
Die folgenden Regeln haben das Ziel, den Code m?glichst gut les- und wartbar
|
|
| 5 |
zu machen. Dazu geh?rt zum Einen, dass der Code einheitlich einger?ckt ist,
|
|
| 4 |
Die folgenden Regeln haben das Ziel, den Code möglichst gut les- und wartbar
|
|
| 5 |
zu machen. Dazu gehört zum Einen, dass der Code einheitlich eingerückt ist,
|
|
| 6 | 6 |
aber auch, dass Mehrdeutigkeit so weit es geht vermieden wird (Stichworte |
| 7 | 7 |
"Klammern" oder "Hash-Keys"). |
| 8 | 8 |
|
| 9 | 9 |
Diese Regeln sind keine Schikane, sondern erleichtern allen das Leben! |
| 10 | 10 |
|
| 11 |
Jeder, der einen Patch schickt, sollte seinen Code vorher ?berpr?fen.
|
|
| 12 |
Einige der Regeln lassen sich automatisch ?berpr?fen, andere nicht.
|
|
| 11 |
Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen.
|
|
| 12 |
Einige der Regeln lassen sich automatisch überprüfen, andere nicht.
|
|
| 13 | 13 |
|
| 14 | 14 |
-------------------------------------------------------------------------- |
| 15 | 15 |
|
| 16 | 16 |
1. Es werden keine echten iTabs sondern Leerzeichen verwendet. |
| 17 | 17 |
|
| 18 |
2. Die Einr?ckung betr?gt zwei Leerzeichen.
|
|
| 18 |
2. Die Einrückung beträgt zwei Leerzeichen.
|
|
| 19 | 19 |
Beispiel: |
| 20 | 20 |
|
| 21 | 21 |
foreach my $row (@data) {
|
| ... | ... | |
| 34 | 34 |
} |
| 35 | 35 |
|
| 36 | 36 |
|
| 37 |
3. ?ffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
|
|
| 37 |
3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
|
|
| 38 | 38 |
der letzte Befehl. |
| 39 | 39 |
Beispiele: |
| 40 | 40 |
|
| ... | ... | |
| 48 | 48 |
... |
| 49 | 49 |
} |
| 50 | 50 |
|
| 51 |
4. Schlie?ende geschweifte Klammern sind so weit einger?ckt wie der Befehl/
|
|
| 52 |
die ?ffnende schlie?ende Klammer, die den Block gestartet hat, und nicht
|
|
| 51 |
4. Schließende geschweifte Klammern sind so weit eingerückt wie der Befehl/
|
|
| 52 |
die öffnende schließende Klammer, die den Block gestartet hat, und nicht
|
|
| 53 | 53 |
auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten. |
| 54 | 54 |
|
| 55 |
5. Die W?rter "else" "elsif", "while" befinden sich auf der gleichen
|
|
| 56 |
Zeile wie schlie?ende geschweifte Klammern.
|
|
| 55 |
5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen
|
|
| 56 |
Zeile wie schließende geschweifte Klammern.
|
|
| 57 | 57 |
Beispiele: |
| 58 | 58 |
|
| 59 | 59 |
if ($form->{sum} > 1000) {
|
| ... | ... | |
| 68 | 68 |
... |
| 69 | 69 |
} until ($a > 0); |
| 70 | 70 |
|
| 71 |
6. Parameter von Funktionsaufrufen m?ssen mit runden Klammern versehen
|
|
| 71 |
6. Parameter von Funktionsaufrufen müssen mit runden Klammern versehen
|
|
| 72 | 72 |
werden. Davon nicht betroffen sind interne perl Funktionen, |
| 73 |
und grep ?hnliche Operatoren.
|
|
| 73 |
und grep ähnliche Operatoren.
|
|
| 74 | 74 |
|
| 75 | 75 |
Beispiel: |
| 76 | 76 |
|
| 77 | 77 |
$main::lxdebug->message("Could not find file.");
|
| 78 | 78 |
%options = map { $_ => 1 } grep { !/^#/ } @config_file;
|
| 79 | 79 |
|
| 80 |
7. Verschiedene Klammern, Ihre Ausdr?cke und Leerzeichen:
|
|
| 80 |
7. Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:
|
|
| 81 | 81 |
|
| 82 | 82 |
Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen |
| 83 |
abgesetzt werden. Logische Klammerungen ebensowenig, Bl?cke schon.
|
|
| 83 |
abgesetzt werden. Logische Klammerungen ebensowenig, Blöcke schon.
|
|
| 84 | 84 |
|
| 85 | 85 |
|
| 86 | 86 |
Beispiel: |
| ... | ... | |
| 98 | 98 |
8. Mehrzeilige Befehle |
| 99 | 99 |
|
| 100 | 100 |
8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen |
| 101 |
aufgeteilt, so sollten diese bis zu der Spalte einger?ckt werden,
|
|
| 101 |
aufgeteilt, so sollten diese bis zu der Spalte eingerückt werden,
|
|
| 102 | 102 |
in der die ersten Funktionsparameter in der ersten Zeile stehen. |
| 103 | 103 |
Beispiel: |
| 104 | 104 |
|
| 105 | 105 |
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
|
| 106 | 106 |
$form->{some_col_value});
|
| 107 | 107 |
|
| 108 |
8.3 Ein Spezialfall ist der tern?re Oprator "?:", der am besten in einer
|
|
| 109 |
?bersichtlichen Tabellenstruktur organisiert wird.
|
|
| 108 |
8.3 Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer
|
|
| 109 |
übersichtlichen Tabellenstruktur organisiert wird.
|
|
| 110 | 110 |
|
| 111 | 111 |
Beispiel: |
| 112 | 112 |
|
| ... | ... | |
| 117 | 117 |
9. Kommentare |
| 118 | 118 |
|
| 119 | 119 |
9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der |
| 120 |
Code einger?ckt sein.
|
|
| 121 |
9.2 Seitliche h?ngende Kommentare sollten einheitlich formatiert werden.
|
|
| 120 |
Code eingerückt sein.
|
|
| 121 |
9.2 Seitliche hängende Kommentare sollten einheitlich formatiert werden.
|
|
| 122 | 122 |
|
| 123 |
9.3 S?mtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch
|
|
| 124 |
zu verfassen. So wie ich keine Lust habe franz?sischen Quelltext zu lesen,
|
|
| 125 |
sollte auch der Lx-Office Quelltext f?r nicht-Deutschsprachige lesbar sein.
|
|
| 123 |
9.3 Sämtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch
|
|
| 124 |
zu verfassen. So wie ich keine Lust habe französischen Quelltext zu lesen,
|
|
| 125 |
sollte auch der Lx-Office Quelltext für nicht-Deutschsprachige lesbar sein.
|
|
| 126 | 126 |
|
| 127 | 127 |
Beispiel: |
| 128 | 128 |
|
| ... | ... | |
| 139 | 139 |
$i *= $const; # do something crazy |
| 140 | 140 |
$i = $n; # recover $i |
| 141 | 141 |
|
| 142 |
10. Hashkeys sollten nur in Anf?hrungszeichen stehen, wenn die Interpolation
|
|
| 143 |
gew?nscht ist.
|
|
| 142 |
10. Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation
|
|
| 143 |
gewünscht ist.
|
|
| 144 | 144 |
|
| 145 | 145 |
Beispiele: |
| 146 | 146 |
|
| ... | ... | |
| 148 | 148 |
$form->{"row_$i"} = $form->{"row_$i"} - 5;
|
| 149 | 149 |
$some_hash{42} = 54;
|
| 150 | 150 |
|
| 151 |
11. Die maximale Zeilenl?nge ist nicht bescr?nkt. Zeilenl?ngen <= 79
|
|
| 151 |
11. Die maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen <= 79
|
|
| 152 | 152 |
helfen unter bestimmten Bedingungen, aber wenn die Lesbarkeit unter |
| 153 | 153 |
kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann |
| 154 | 154 |
ist Lesbarkeit vorzuziehen. |
| 155 | 155 |
|
| 156 |
Als Beispiel sei print_options aus bin/mozilla/io.pl angef?hrt.
|
|
| 156 |
Als Beispiel sei print_options aus bin/mozilla/io.pl angeführt.
|
|
| 157 | 157 |
|
| 158 |
12. Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerw?nscht.
|
|
| 159 |
Sie f?hren zu unn?tigen Whitespace?nderungen die diffs verf?lschen.
|
|
| 158 |
12. Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerwünscht.
|
|
| 159 |
Sie führen zu unnötigen Whitespaceänderungen die diffs verfälschen.
|
|
| 160 | 160 |
|
| 161 |
Emacs und vim haben beide recht einfache Methoden daf?r:
|
|
| 161 |
Emacs und vim haben beide recht einfache Methoden dafür:
|
|
| 162 | 162 |
emacs kennt das Kommande nuke-trailing-whitespace, |
| 163 |
vim macht das gleiche manuell ?ber :%s/\s\+$//e, mit
|
|
| 163 |
vim macht das gleiche manuell über :%s/\s\+$//e, mit
|
|
| 164 | 164 |
:au BufWritePre * :%s/\s\+$//e |
| 165 | 165 |
wird das an speichern gebunden. |
| 166 | 166 |
|
| ... | ... | |
| 168 | 168 |
|
| 169 | 169 |
In der Vergangenheit wurde versucht perltidy zu verwenden um einen |
| 170 | 170 |
einheitlichen Stil zu erlangen, es hat sich aber gezeigt, dass Perltidys |
| 171 |
sehr eigenwilliges Verhaltes was Zeilenumbr?che angeht oftmals gut
|
|
| 172 |
formatierten Code zerst?rt. F?r den Interessierten sind hier die perltidy
|
|
| 171 |
sehr eigenwilliges Verhaltes was Zeilenumbrüche angeht oftmals gut
|
|
| 172 |
formatierten Code zerstört. Für den Interessierten sind hier die perltidy
|
|
| 173 | 173 |
Optionen, die grob den beschriebenen Richtlinien entsprechen. |
| 174 | 174 |
|
| 175 | 175 |
-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm |
| ... | ... | |
| 181 | 181 |
Lx-Office bietet mit dem LXDebug Modul einen brauchbaren Trace/Debug |
| 182 | 182 |
Mechanismus, es gibt also keinen Grund nach STDERR zu schreiben. |
| 183 | 183 |
|
| 184 |
Die LXDebug Methode "message" nimmt als ersten Paramter au?erdem eine
|
|
| 185 |
Flagmaske, f?r die die Meldung angezeigt wird, wobei "0" immer angezeigt
|
|
| 184 |
Die LXDebug Methode "message" nimmt als ersten Paramter außerdem eine
|
|
| 185 |
Flagmaske, für die die Meldung angezeigt wird, wobei "0" immer angezeigt
|
|
| 186 | 186 |
wird. Sollte Meldungen sollten nicht eingecheckt werden, und werden in den |
| 187 |
meisten F?llen auch vom Repository zur?ckgewiesen.
|
|
| 187 |
meisten Fällen auch vom Repository zurückgewiesen.
|
|
| 188 | 188 |
|
| 189 |
14. Alle neuen Module m?ssen use strict verwenden.
|
|
| 189 |
14. Alle neuen Module müssen use strict verwenden.
|
|
| 190 | 190 |
|
| 191 | 191 |
$form, $auth, $locale, $lxdebug, %myconfig sowie der Inhalt der lx-erp.conf |
| 192 | 192 |
werden derzeit aus dem main package importiert. Alle anderen Konstrukte |
Auch abrufbar als: Unified diff
Dokumentation komplett nach utf8 konvertiert.