Merge von 568 aus unstable.

[mfinanz.git] / doc / programmierstilrichtlinien.txt

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!

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 -- und seine Veränderung danach noch einmal
kurz testen! Damit werden einige der nachfolgenden Regeln automatisch
befolgt, andere hingegen nicht. Dort, wo keine perltidy-Optionen
angegeben sind, muss der Programmierer selbst für die Einhaltung
sorgen.

(A) "Inhalt"
============

1. Alle Variablen müssen in dem Block, in dem sie benutzt werden mit
   "my $variable;" oder mit "local *FILEHANDLE;" deklariert werden.
   Neue globale Variablen einzuführen ist nicht erlaubt!

2. Variablennamen

  2.1 Alle Variablennamen müssen sinnvoll sein. "$i" als Schleifenzähler zu
      nehmen ist in Ordnung. Sobald es aber über einen trivialen Fall
      hinausgeht ist der Variable ein Name zu geben, der den Inhalt wieder-
      spiegelt. Beispielsweise "$rowcount" für die Anzahl der Zeilen/
      Positionen in einer Rechnung oder "$net_price" für den Nettopreis.

  2.2 Variablen, die einfach den Inhalt einer Datenbankspalte beeinhalten,
      sollten so benannt werden, wie die Datenbankspalte ebenfalls heißt.

  2.3 Variablennamen sollten in Englisch gehalten sein, weil der Rest
      des Programms ebenfalls in Englisch gehalten ist. Für Begriffe,
      für die es keine englischen Entsprechungen gibt, sind deutsche
      Variablennamen in Ordnung.

3. Die Schreibweise von Variablen sollte komplett klein ein. Zusammengesetzte
   Namen sollten mit Unterstrichen getrennt werden. Beispiel: "$net_price".

4. Kommentare

  4.1 Kommentare beziehen sich immer auf Code in der gleichen Zeile, wenn
      der Kommentar am rechten Rand steht, oder auf den nachfolgen Code.

  4.2 Codeteile, deren Funktion nicht auf den ersten Blick ersichtlich ist,
      sollten kommentiert werden. Der Kommentar sollte kurz beschreiben,
      was der Codeteil macht, eventuelle Nebenwirkungen oder Probleme
      auflisten.

  4.3 Kommentare der Art, dass Benutzer X am Datum Y den Teil Z geändert
      hat, sind nicht notwendig. Dafür gibt es die SVN-Commit-Nachrichten,
      die all diese Informationen enthalten bzw. enthalten müssen.

  4.4 Funktionen sollten kommentiert werden. Dazu wird vor der Funktion
      ein Kommentarblock erstellt, der beschreibt, was diese Funktion
      tut. Zusätzlich sollte aufgezählt werden, welche Parameter die
      Funktion erwartet und welche Bedeutung diese haben. Der Rückgabewert
      ist ebenfalls zu dokumentieren.

5. Alle Texte/Begriffe, die ausgegeben werden, müssen mit
   $text->locale('Begriff'); ausgegeben werden, damit diese Begriffe
   übersetzt werden können. Das betrifft aber nur Begriffe, die einzeln
   übersetzbar sind, natürlich nicht für z.B. HTML-Code.

6. Änderungen in den Kernbestandteilen von Lx-Office, die nur der Anbindung
   von Modulen dienen, die wiederum nicht Bestandteil der offiziellen
   Distribution sind, müssen durch eine Konfigurationsvariable abschaltbar
   sein. Damit soll verhindert werden, dass solcher Code ausgeführt wird,
   wenn das Modul nicht installiert ist, da dieser Code ausschließlich von
   den Programmierern dieses Moduls getestet werden kann.





(B) "Optik" -- Sachen, die die Form betreffen
=============================================

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 {
     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->{"path"} eq "bin/mozilla") {
     ...
   }

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) {
     ...
   } elsif ($form->{"sum"} > 0) {
     ...
   } else {
     ...
   }

   do {
     ...
   } 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!

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

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,
      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 zusätzlich zwei Leerzeichen einzurücken.
      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 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.

    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 Zeilenlänge ist nicht beschrä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.

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




(C) Liste der perltidy-Optionen
===============================

Vollständige Liste aller Optionen, die ich für perltidy benutze. Diese
können 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