4.5. Stil-Richtlinien

4.5. Stil-Richtlinien
Zurück	Kapitel 4. Entwicklerdokumentation	Weiter

+ 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! +

+ Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere + nicht. +

+ Es werden keine echten Tabs sondern Leerzeichen verwendet. +

+ Die Einrückung beträgt zwei Leerzeichen. Beispiel: +

foreach my $row (@data) {
+  if ($flag) {
+    # do something with $row
+  }
+
+  if ($use_modules) {
+    $row->{modules} = MODULE->retrieve(
+      id   => $row->{id},
+      date => $use_now ? localtime() : $row->{time},
+    );
+  }
+
+  $report->add($row);
+}

Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie der letzte Befehl. Beispiele:
```
sub debug {
+  ...
+}
```
oder
```
if ($form->{item_rows} > 0) {
+  ...
+}
```
+ 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. +
+ Die Wörter "else", "elsif", "while" befinden sich auf der gleichen + Zeile wie schließende geschweifte Klammern. Beispiele: +
```
if ($form->{sum} > 1000) {
+  ...
+} elsif ($form->{sum} > 0) {
+  ...
+} else {
+  ...
+}
+
+do {
+  ...
+} until ($a > 0);
```
+ Parameter von Funktionsaufrufen müssen mit runden Klammern versehen werden. Davon nicht betroffen sind interne Perl-Funktionen, + und grep-ähnliche Operatoren. Beispiel: +
```
$main::lxdebug->message("Could not find file.");
+%options = map { $_ => 1 } grep { !/^#/ } @config_file;
```

+ Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen: +

+ Generell gilt: Hashkeys und Arrayindices sollten nicht durch Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig, + Blöcke schon. Beispiel: +

if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
+  ...
+}
+
+$array[$i + 1]             = 4;
+$form->{sum}              += $form->{"row_$i"};
+$form->{ $form->{index} } += 1;
+
+map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;

+ Mehrzeilige Befehle +
1. + Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerückt + werden, in der die ersten Funktionsparameter in der ersten Zeile stehen. Beispiel: +
```
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
+                    $form->{some_col_value});
```
2. + Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer übersichtlichen Tabellenstruktur organisiert + wird. Beispiel: +
```
my $rowcount = $form->{"row_$i"} ? $i
+             : $form->{oldcount} ? $form->{oldcount} + 1
+             :                     $form->{rowcount} - $form->{rowbase};
```
+ Kommentare +
1. Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der Code eingerückt sein.
2. Seitliche hängende Kommentare sollten einheitlich formatiert werden.
3. + Sämtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch zu verfassen. So wie ich keine Lust habe, französischen + Quelltext zu lesen, sollte auch der Lx-Office Quelltext für nicht-Deutschsprachige lesbar sein. Beispiel: +
```
my $found = 0;
+while (1) {
+  last if $found;
+
+  # complicated check
+  $found = 1 if //
+}
+
+$i  = 0        # initialize $i
+$n  = $i;      # save $i
+$i *= $const;  # do something crazy
+$i  = $n;      # recover $i
```
+ Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation gewünscht ist. Beispiel: +
```
$form->{sum}      = 0;
+$form->{"row_$i"} = $form->{"row_$i"} - 5;
+$some_hash{42}    = 54;
```
+ Die maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber + wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann ist Lesbarkeit vorzuziehen. +
+ Als Beispiel sei die Funktion print_options aus bin/mozilla/io.pl angeführt. +
+ Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerwünscht. Sie führen zu unnötigen Whitespaceänderungen, die + diffs verfälschen. +
+ Emacs und vim haben beide recht einfache Methoden zur Entfernung von trailing whitespace. Emacs kennt das Kommande + nuke-trailing-whitespace, vim macht das gleiche manuell über :%s/\s\+$//e Mit :au + BufWritePre * :%s/\s\+$//e wird das an Speichern gebunden. +
+ Es wird kein perltidy verwendet. +
+ In der Vergangenheit wurde versucht, perltidy zu verwenden, um einen einheitlichen Stil zu erlangen. Es hat + sich aber gezeigt, dass perltidys sehr eigenwilliges Verhalten, was Zeilenumbrüche angeht, oftmals gut + formatierten Code zerstört. Für den Interessierten sind hier die perltidy-Optionen, die grob den + beschriebenen Richtlinien entsprechen: +
```
-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
```
+ + STDERR ist tabu. Unkonditionale Debugmeldungen auch. +
+ Lx-Office bietet mit dem Modul LXDebug einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen + Grund, nach STDERR zu schreiben. +
+ Die LXDebug-Methode "message" nimmt als ersten Paramter außerdem eine Flagmaske, für + die die Meldung angezeigt wird, wobei "0" immer angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden und werden in + den meisten Fällen auch vom Repository zurückgewiesen. +
+ Alle neuen Module müssen use strict verwenden. +
+ + $form, $auth, $locale, $lxdebug und + %myconfig werden derzeit aus dem main package importiert (siehe Globale Variablen. Alle anderen + Konstrukte sollten lexikalisch lokal gehalten werden. +

Zurück	Nach oben	Weiter
4.4. Translations and languages	Zum Anfang	4.6. Dokumentation erstellen