Lx-Office Style Guide
---------------------

Die folgenden Regeln haben das Ziel, den Code mglichst gut les- und wartbar
zu machen. Dazu gehrt zum Einen, dass der Code einheitlich eingerckt 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!

Zum einfachen Formartieren von Perl-Scripten gibt es das Tool "perltidy",
das man weitgehend konfigurieren kann. Bei fast allen nachfolgenden Punkten
sind die dazugehrigen 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
sind, muss der Programmierer selbst fr die Einhaltung sorgen.

--------------------------------------------------------------------------

1. Es werden keine "echten" TAB-Zeichen sondern Leerzeichen verwendet.
   Perltidy: -nt

2. Die Einrckung betrgt zwei Leerzeichen.
   Perltidy: -i=2
   Beispiel:

   sub debug {
     print(STDERR "Debugging.\n");
   }

3. ffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
   der letzte Befehl.
   Perltidy: -nbl -nsbl -bar
   Beispiele:

   sub debug {
   ...
   }

   oder

   if ($form->{item_rows} > 0) {
     ...
   }

4. Schlieende geschweifte Klammern sind so weit eingerckt wie der Befehl/
   die ffnende schlieende 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 Wrter "else" "elsif", "while" befinden sich auf der gleichen
   Zeile wie schlieende geschweifte Klammern.
   Perltidy: -ce
   Beispiele:

   if ($form->{"sum"} > 1000) {
     ...
   } elsif ($form->{"sum"} > 0) {
     ...
   } else {
     ...
   }

   do {
     ...
   } while ($a > 0);

6. Parameter von Funktionsaufrufen mssen mit runden Klammern versehen
   werden.

   Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss
   selber darauf achten!

   Beispiel:

   debug("Konnte Datei nicht oeffnen.\n");

7. Verschiedene Klammern

  7.1 Aufeinander folgende runde Klammern sollten nicht durch Leerzeichen
      abgesetzt werden.
      Perltidy: -pt=2
      Beispiel:

      if (($form->{"debug"} == 1) && (($form->{"sum"} - 100) < 0)) {
        ...
      }

  7.2 Nach und vor eckigen Klammern sollten keine Leerzeichen stehen.
      Perltidy: -sbt=2
      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}"};

      $form->{ $form->{"index"} } += 1;

  7.4 Nach und vor geschweiften Klammern, die Codeblcke beschrnken,
      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;

8. Mehrzeilige Befehle

  8.1 Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen
      aufgeteilt, so mssen diese bis zu der Spalte eingerckt 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"});

  8.2 Wird ein Befehl auf einer neuen Zeile forgesetzt, so ist ab der
      zweiten Zeile zustzlich zwei Leerzeichen einzurcken.
      Perltidy: -ci=2
      Beispiel:

      my $rowcount =
        $form->{"row_$i"} ? $i : $form->{"rowcount"} - $form->{"rowbase"};

9. Kommentare

  9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der
      Code eingerckt sein.
      Perltidy: -ibc

  9.2 Seitliche hngende Kommentare sollten einheitlich formatiert werden.
      Perltidy: -hsc

10. Hash-Keys sind, sofern es sich um Zeichenketten und nicht um
    Nummern handelt, in Anfhrungszeichen zu setzen.

    Achtung: perltidy kann dieses nicht erledigen. Der Programmierer muss
    selber darauf achten!

    Beispiele:

    $form->{"sum"} = 0;
    $form->{"row_$i"} = $form->{"row_$i"} - 5;
    $some_hash{42} = 54;

11. Die Maximale Zeilenlnge ist nicht bescrnkt. Zeilenlngen <= 79
    helfen, weil sie dann im Textmodus / per SSH deutlich besser lesbar
    sind. Oft genug ist es aber nicht mglich oder nur unter groen
    Verrenkungen, diese Vorgabe einzuhalten.

    Zeilen sollten nicht lnger als 79 Zeichen sein.
    Perltidy: -l=79

--------------------------------------------------------------------------

Vollstndige Liste aller Optionen, die ich fr perltidy benutze. Diese
knnen in ~/.perltidyrc geschrieben werden:

-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
