Anpassung für oesterreichischen Kontenrahmen. Verhält sich neutral ggue. anderen...
[kivitendo-erp.git] / doc / programmierstilrichtlinien.txt
1 Lx-Office Style Guide
2 ---------------------
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,
6 aber auch, dass Mehrdeutigkeit so weit es geht vermieden wird (Stichworte
7 "Klammern" oder "Hash-Keys").
8
9 Diese Regeln sind keine Schikane, sondern erleichtern allen das Leben!
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 Jeder, der einen Patch schickt, sollte sein Script vorher durch perltidy
18 laufen lassen. Damit werden einige der nachfolgenden Regeln automatisch
19 befolgt, andere hingegen nicht. Dort, wo keine perltidy-Optionen angegeben
20 sind, muss der Programmierer selbst für die Einhaltung sorgen.
21
22 --------------------------------------------------------------------------
23
24 1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet.
25    Perltidy: -nt
26
27 2. Die Einrückung beträgt zwei Leerzeichen.
28    Perltidy: -i=2
29    Beispiel:
30
31    sub debug {
32      print(STDERR "Debugging.\n");
33    }
34
35 3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
36    der letzte Befehl.
37    Perltidy: -nbl -nsbl -bar
38    Beispiele:
39
40    sub debug {
41    ...
42    }
43
44    oder
45
46    if ($form->{item_rows} > 0) {
47      ...
48    }
49
50 4. Schließende geschweifte Klammern sind so weit eingerückt wie der Befehl/
51    die öffnende schließende Klammer, die den Block gestartet hat, und nicht
52    auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten.
53    Perltidy: macht's automatisch
54
55 5. Die Wörter "else" "elsif", "while" befinden sich auf der gleichen
56    Zeile wie schließende geschweifte Klammern.
57    Perltidy: -ce
58    Beispiele:
59
60    if ($form->{"sum"} > 1000) {
61      ...
62    } elsif ($form->{"sum"} > 0) {
63      ...
64    } else {
65      ...
66    }
67
68    do {
69      ...
70    } while ($a > 0);
71
72 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!
77
78    Beispiel:
79
80    debug("Konnte Datei nicht oeffnen.\n");
81
82 7. Verschiedene Klammern
83
84   7.1 Aufeinander folgende runde Klammern sollten nicht durch Leerzeichen
85       abgesetzt werden.
86       Perltidy: -pt=2
87       Beispiel:
88
89       if (($form->{"debug"} == 1) && (($form->{"sum"} - 100) < 0)) {
90         ...
91       }
92
93   7.2 Nach und vor eckigen Klammern sollten keine Leerzeichen stehen.
94       Perltidy: -sbt=2
95       Beispiel:
96
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}"};
104
105       $form->{ $form->{"index"} } += 1;
106
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;
115
116 8. Mehrzeilige Befehle
117
118   8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen
119       aufgeteilt, so müssen diese bis zu der Spalte eingerückt werden,
120       in der die ersten Funktionsparameter in der ersten Zeile stehen.
121       Perltidy: -lp -vt=1 -vtc=1
122       Beispiel:
123
124       $sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
125                            $form->{"some_col_value"});
126
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       Beispiel:
131
132       my $rowcount =
133         $form->{"row_$i"} ? $i : $form->{"rowcount"} - $form->{"rowbase"};
134
135 9. Kommentare
136
137   9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der
138       Code eingerückt sein.
139       Perltidy: -ibc
140
141   9.2 Seitliche hängende Kommentare sollten einheitlich formatiert werden.
142       Perltidy: -hsc
143
144 10. Hash-Keys sind, sofern es sich um Zeichenketten und nicht um
145     Nummern handelt, in Anführungszeichen zu setzen.
146
147     Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss
148     selber darauf achten!
149
150     Beispiele:
151
152     $form->{"sum"} = 0;
153     $form->{"row_$i"} = $form->{"row_$i"} - 5;
154     $some_hash{42} = 54;
155
156 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.
160
161     Zeilen sollten nicht länger als 79 Zeichen sein.
162     Perltidy: -l=79
163
164 --------------------------------------------------------------------------
165
166 Vollständige Liste aller Optionen, die ich für perltidy benutze. Diese
167 können in ~/.perltidyrc geschrieben werden:
168
169 -syn
170 -i=2
171 -nt
172 -pt=2
173 -sbt=2
174 -ci=2
175 -ibc
176 -hsc
177 -noll
178 -nsts
179 -nsfs
180 -asc
181 -dsm
182 -aws
183 -bbc
184 -bbs
185 -bbb
186 -mbl=1
187 -nsob
188 -ce
189 -nbl
190 -nsbl
191 -cti=0
192 -bbt=0
193 -bar
194 -l=79
195 -lp
196 -vt=1
197 -vtc=1