X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fprogrammierstilrichtlinien.txt;h=128a6f8c2f90d154dbe3138765cf7390288574f8;hb=a35a796b017f7ca94f7c881d1b96e0c3cdccd96e;hp=8da0febb3000d3045c58016413787dff0de31170;hpb=d319704a66e9be64da837ccea10af6774c2b0838;p=kivitendo-erp.git

diff --git a/doc/programmierstilrichtlinien.txt b/doc/programmierstilrichtlinien.txt
index 8da0febb3..128a6f8c2 100644
--- a/doc/programmierstilrichtlinien.txt
+++ b/doc/programmierstilrichtlinien.txt
@@ -8,12 +8,6 @@ aber auch, dass Mehrdeutigkeit so weit es geht vermieden wird (Stichworte
 
 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
@@ -22,10 +16,8 @@ sind, muss der Programmierer selbst f
 --------------------------------------------------------------------------
 
 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 {
@@ -34,32 +26,29 @@ sind, muss der Programmierer selbst f
 
 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") {
+   if ($form->{item_rows} > 0) {
      ...
    }
 
 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) {
+   if ($form->{sum} > 1000) {
      ...
-   } elsif ($form->{"sum"} > 0) {
+   } elsif ($form->{sum} > 0) {
      ...
    } else {
      ...
@@ -70,101 +59,105 @@ sind, muss der Programmierer selbst f
    } 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!
+   werden. Davon nicht betroffen sind interne perl Funktionen.
 
    Beispiel:
 
-   debug("Konnte Datei nicht oeffnen.\n");
+   $main::lxdebug->message("Could not find file.");
+   %options = map { $_ => 1 } grep { !/^#/ } @config_file;
 
-7. Verschiedene Klammern
+7. Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:
 
-  7.1 Aufeinander folgende runde Klammern sollten nicht durch Leerzeichen
-      abgesetzt werden.
-      Perltidy: -pt=2
-      Beispiel:
+  Generell gilt: Hashkeys und Arrayindices sollten _nicht_ durch Leerzeichen
+  abgesetzt werden. Logische Klammerungen ebensowenig, Blöcke schon.
 
-      if (($form->{"debug"} == 1) && (($form->{"sum"} - 100) < 0)) {
-        ...
-      }
 
-  7.2 Nach und vor eckigen Klammern sollten keine Leerzeichen stehen.
-      Perltidy: -sbt=2
-      Beispiel:
+  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}"};
+      if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
+        ...
+      }
 
-      $form->{ $form->{"index"} } += 1;
+      $array[$i + 1]             = 4;
+      $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;
+      map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;
 
 8. Mehrzeilige Befehle
 
   8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen
-      aufgeteilt, so m[ssen diese bis zu der Spalte eingerückt werden,
+      aufgeteilt, so sollten diese bis zu der Spalte eingerückt werden,
       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"});
+                           $form->{some_col_value});
+
+  8.3 Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer
+      übersichtlichen Tabellenstruktur organisiert wird.
 
-  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"};
+      my $rowcount = $form->{"row_$i"} ? $i
+                   : $form->{oldcount} ? $form->{oldcount} + 1
+                   :                     $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.
+  9.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;
 
-    Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss
-    selber darauf achten!
+        # complicated check
+        $found = 1 if //
+      }
+
+      $i = 0         # initialize $i
+      $n = $i;       # save $i
+      $i *= $const;  # do something crazy
+      $i = $n;       # recover $i
+
+10. Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation
+    gewünscht ist.
 
     Beispiele:
 
-    $form->{"sum"} = 0;
+    $form->{sum}      = 0;
     $form->{"row_$i"} = $form->{"row_$i"} - 5;
-    $some_hash{42} = 54;
+    $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.
+    helfen unter bestimmten Bedingungen, aber wenn die Lesbarkeit unter
+    kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann
+    ist Lesbarkeit vorzuziehen.
 
-    Zeilen sollten nicht länger als 79 Zeichen sein.
-    Perltidy: -l=79
+    Als Beispiel sei print_options aus bin/mozilla/io.pl angeführt.
 
---------------------------------------------------------------------------
+12. 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 einfach Methoden dafür:
+    emacs kennt das Kommande nuke-trailing-whitespace,
+    vim macht das gleiche manuell über :%s/\s\+$//e
+
+12. Es wird kein perltidy verwendet.
 
-Vollständige Liste aller Optionen, die ich für perltidy benutze. Diese
-können in ~/.perltidyrc geschrieben werden:
+    In der Vergangenheit wurde versucht perltidy zu verwenden um einen
+    einheitlichen Stil zu erlangen, es hat sich aber gezeigt, dass Perltidys
+    sehr eigenwilliges Verhaltes was Zeilenumbrüche angeht oftmals gut
+    formatierten Code zerstört. Für den Interessierten, hier sind die perltidy
+    Optionen die grob den beschriebenen Richtlinien entsprechen.
 
 -syn
 -i=2