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

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.

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

1. Es werden keine echten iTabs sondern Leerzeichen verwendet.

2. 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);
   }


3. Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie
   der letzte Befehl.
   Beispiele:

   sub debug {
     ...
   }

   oder

   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.

5. 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);

6. 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;

7. 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;

8. Mehrzeilige Befehle

  8.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});

  8.3 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};

9. Kommentare

  9.1 Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der
      Code eingerückt sein.
  9.2 Seitliche hängende Kommentare sollten einheitlich formatiert werden.

  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;

        # 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->{"row_$i"} = $form->{"row_$i"} - 5;
    $some_hash{42}    = 54;

11. Die maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen <= 79
    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 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 einfache Methoden dafür:
    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.

12. 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 Verhaltes 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

13. STDERR ist tabu. Unkonditionale Debugmeldungen auch.

    Lx-Office bietet mit dem LXDebug Modul 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. Sollte Meldungen sollten nicht eingecheckt werden, und werden in den
    meisten Fällen auch vom Repository zurückgewiesen.

14. Alle neuen Module müssen use strict verwenden.

    $form, $auth, $locale, $lxdebug, %myconfig sowie der Inhalt der lx-erp.conf
    werden derzeit aus dem main package importiert. Alle anderen Konstrukte
    sollten lexikalisch lokal gehalten werden.