X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fhtml%2Fch04s05.html;h=9d3743f079daf0aaa39a4a361072f0fac670c84f;hb=075bd42af8885aee3c18fe055a2c82b8b43f4cea;hp=2709135285d7b8b27ba6ecfc7693d87c0d2e6304;hpb=c5dd616c7b24d70644615628af9b18274329f942;p=kivitendo-erp.git diff --git a/doc/html/ch04s05.html b/doc/html/ch04s05.html index 270913528..9d3743f07 100644 --- a/doc/html/ch04s05.html +++ b/doc/html/ch04s05.html @@ -1,13 +1,13 @@ - - 4.5. Stil-Richtlinien
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 + + 4.5. Stil-Richtlinien

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 + ü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) {
+          verwendet.

  3. Die Einrückung beträgt zwei Leerzeichen. Beispiel:

    foreach my $row (@data) {
   if ($flag) {
     # do something with $row
   }
@@ -20,17 +20,17 @@
   }
 
   $report->add($row);
-}

  4. Öffnende geschweifte Klammern befinden sich auf der gleichen +}

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

    sub debug {
   ...
 }

    oder

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

  6. Schließende geschweifte Klammern sind so weit eingerückt wie - der Befehl / die öffnende schließende Klammer, die den Block +}

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

  8. Die Wörter "else", + Beispiele wie bei 3. gelten.

  9. Die Wörter "else", "elsif", "while" befinden - sich auf der gleichen Zeile wie schließende geschweifte Klammern. + sich auf der gleichen Zeile wie schließende geschweifte Klammern. Beispiele:

    if ($form->{sum} > 1000) {
   ...
 } elsif ($form->{sum} > 0) {
@@ -41,12 +41,12 @@
 
 do {
   ...
-} until ($a > 0);

  10. Parameter von Funktionsaufrufen müssen mit runden Klammern +} until ($a > 0);

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

  12. Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:

    Generell gilt: Hashkeys und Arrayindices sollten nicht durch + und grep-ähnliche Operatoren. Beispiel:

    $main::lxdebug->message("Could not find file.");
+%options = map { $_ => 1 } grep { !/^#/ } @config_file;

  13. 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)) {
+          Blöcke schon. Beispiel:
    if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
   ...
 }
 
@@ -55,19 +55,19 @@ $form->{sum}              += $form->{"row_$i"};
 $form->{ $form->{index} } += 1;
 
 map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;

  14. Mehrzeilige Befehle

    1. Werden die Parameter eines Funktionsaufrufes auf mehrere - Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerückt + 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 + $form->{some_col_value});

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

  15. 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 + soweit wie der Code eingerückt sein.

    4. Seitliche hängende Kommentare sollten einheitlich + formatiert werden.

    5. 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. + französischen Quelltext zu lesen, sollte auch der kivitendo + Quelltext für nicht-Deutschsprachige lesbar sein. Beispiel:

      my $found = 0;
 while (1) {
   last if $found;
@@ -79,42 +79,42 @@ while (1) {
 $i  = 0        # initialize $i
 $n  = $i;      # save $i
 $i *= $const;  # do something crazy
-$i  = $n;      # recover $i

  16. Hashkeys sollten nur in Anführungszeichen stehen, wenn die - Interpolation gewünscht ist. Beispiel:

    $form->{sum}      = 0;
+$i  = $n;      # recover $i

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

  • Die maximale Zeilenlänge ist nicht beschränkt. Zeilenlängen +$some_hash{42} = 54;

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

  • 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 + bin/mozilla/io.pl angeführt.

  • 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 + manuell über :%s/\s\+$//e Mit :au BufWritePre * :%s/\s\+$//e wird das an Speichern gebunden.

  • 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 + 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

  • STDERR ist tabu. Unkonditionale - Debugmeldungen auch.

    Lx-Office bietet mit dem Modul LXDebug + Debugmeldungen auch.

    kivitendo 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 + "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.

  • Alle neuen Module müssen use strict verwenden.

    + und werden in den meisten Fällen auch vom Repository + zurückgewiesen.

  • 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
    \ No newline at end of file + Konstrukte sollten lexikalisch lokal gehalten werden.

    Zurück Nach oben Weiter
    4.4. Translations and languages Zum Anfang 4.6. Dokumentation erstellen
    \ No newline at end of file