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

4.5. Stil-Richtlinien

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

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

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

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

  11. Die maximale Zeilenl�nge ist nicht beschr�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.

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

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

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

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