X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fhtml%2Fch04s06.html;h=6eddda524a79c08a4c1990f59a9d12aaa62fcb3b;hb=c62a6cabffc11bdb2d3fda2025fef2f3d07c5ba9;hp=d12376ec421c43f942ff15637698dc3b0d37193b;hpb=d2ab33ea45cee261d98267e4c336e5cd7be8521e;p=kivitendo-erp.git diff --git a/doc/html/ch04s06.html b/doc/html/ch04s06.html index d12376ec4..6eddda524 100644 --- a/doc/html/ch04s06.html +++ b/doc/html/ch04s06.html @@ -1,120 +1,115 @@ - 4.6. Stil-Richtlinien
4.6. Stil-Richtlinien
Zurück Kapitel 4. Entwicklerdokumentation Weiter

4.6. 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
-  }
+   4.6. Die kivitendo-Test-Suite
    4.6. Die kivitendo-Test-Suite
    Zurück Kapitel 4. Entwicklerdokumentation Weiter
    4.6. Die kivitendo-Test-Suite
    4.6.1. Einführung
    kivitendo enthält eine Suite für automatisierte Tests. Sie
+        basiert auf dem Standard-Perl-Modul
+        Test::More.
    Die grundlegenden Fakten sind:
    • Alle Tests liegen im Unterverzeichnis
+            t/.
    • Ein Script (bzw. ein Test) in t/
+            enthält einen oder mehrere Testfälle.
    • Alle Dateinamen von Tests enden auf .t.
+            Es sind selbstständig ausführbare Perl-Scripte.
    • Die Test-Suite besteht aus der Gesamtheit aller Tests,
+            sprich aller Scripte in t/, deren Dateiname
+            auf .t endet.
    4.6.2. Voraussetzungen
    Für die Ausführung werden neben den für kivitendo eh schon
+        benötigten Module noch weitere Perl-Module benötigt. Diese
+        sind:
    • 
+                     Test::Deep (Debian-Paketname:
+            libtest-deep-perl; Fedora:
+            perl-Test-Deep; openSUSE:
+            perl-Test-Deep)
    • 
+                     Test::Exception (Debian-Paketname:
+            libtest-exception-perl; Fedora:
+            perl-Test-Exception; openSUSE:
+            perl-Test-Exception)
    • 
+                     Test::Output (Debian-Paketname:
+            libtest-output-perl; Fedora:
+            perl-Test-Output; openSUSE:
+            perl-Test-Output)
    • 
+                     Test::Harness 3.0.0 oder höher. Dieses
+            Modul ist ab Perl 5.10.1 Bestandteil der Perl-Distribution und
+            kann für frühere Versionen aus dem CPAN bezogen werden.
    • 
+                     LWP::Simple aus dem Paket
+            libwww-perl (Debian-Panetname:
+            libwww-perl; Fedora:
+            perl-libwww-perl; openSUSE:
+            perl-libwww-perl)
    • 
+                     URI::Find (Debian-Panetname:
+            liburi-find-perl; Fedora:
+            perl-URI-Find; openSUSE:
+            perl-URI-Find)
    • 
+                     Sys::CPU (Debian-Panetname:
+            libsys-cpu-perl; Fedora und openSUSE: nicht
+            vorhanden)
    • 
+                     Thread::Pool::Simple (Debian-Panetname:
+            libthread-pool-simple-perl; Fedora und
+            openSUSE: nicht vorhanden)
    Weitere Voraussetzung ist, dass die Testsuite ihre eigene
+        Datenbank anlegen kann, um Produktivdaten nicht zu gefährden. Dazu
+        müssen in der Konfigurationsdatei im Abschnit
+        testing/database Datenbankverbindungsparameter
+        angegeben werden. Der hier angegebene Benutzer muss weiterhin das
+        Recht haben, Datenbanken anzulegen und zu löschen.
    Der so angegebene Benutzer muss nicht zwingend über
+        Super-User-Rechte verfügen. Allerdings gibt es einige
+        Datenbank-Upgrades, die genau diese Rechte benötigen. Für den Fall
+        kann man in diesem Konfigurationsabschnitt einen weiteren
+        Benutzeraccount angeben, der dann über Super-User-Rechte verfügt, und
+        mit dem die betroffenen Upgrades durchgeführt werden. In der
+        Beispiel-Konfigurationsdatei finden Sie die benötigten
+        Parameter.
    4.6.3. Existierende Tests ausführen
    Es gibt mehrere Möglichkeiten zum Ausführen der Tests: entweder,
+        man lässt alle Tests auf einmal ausführen, oder man führt gezielt
+        einzelne Scripte aus. Für beide Fälle gibt es das Helferscript
+        t/test.pl.
    Will man die komplette Test-Suite ausführen, so muss man einfach
+        nur t/test.pl ohne weitere Parameter aus dem
+        kivitendo-Basisverzeichnis heraus ausführen.
    Um einzelne Test-Scripte auszuführen, übergibt man deren Namen
+        an t/test.pl. Beispielsweise:
    t/test.pl t/form/format_amount.t t/background_job/known_jobs.t
    4.6.4. Bedeutung der verschiedenen Test-Scripte
    Die Test-Suite umfasst Tests sowohl für Funktionen als auch für
+        Programmierstil. Einige besonders zu erwähnende, weil auch während der
+        Entwicklung nützliche Tests sind:
    • 
+                     t/001compile.t -- compiliert alle
+            Quelldateien und bricht bei Fehlern sofort ab
    • 
+                     t/002goodperl.t -- überprüft alle
+            Perl-Dateien auf Anwesenheit von 'use
+            strict'-Anweisungen
    • 
+                     t/003safesys.t -- überprüft Aufrufe von
+            system() und exec() auf
+            Gültigkeit
    • 
+                     t/005no_tabs.t -- überprüft, ob Dateien
+            Tab-Zeichen enthalten
    • 
+                     t/006spelling.t -- sucht nach häufigen
+            Rechtschreibfehlern
    • 
+                     t/011pod.t -- überprüft die Syntax von
+            Dokumentation im POD-Format auf Gültigkeit
    Weitere Test-Scripte überprüfen primär die Funktionsweise
+        einzelner Funktionen und Module.
    4.6.5. Neue Test-Scripte erstellen
    Es wird sehr gern gesehen, wenn neue Funktionalität auch gleich
+        mit einem Test-Script abgesichert wird. Auch bestehende Funktion darf
+        und soll ausdrücklich nachträglich mit Test-Scripten abgesichert
+        werden.
    4.6.5.1. Ideen für neue Test-Scripte, die keine konkreten Funktionen
+          testen
    Ideen, die abgesehen von Funktionen noch nicht umgesetzt
+          wurden:
    • Überprüfung auf fehlende symbolische Links
    • Suche nach Nicht-ASCII-Zeichen in Perl-Code-Dateien (mit
+              gewissen Einschränkungen wie das Erlauben von deutschen
+              Umlauten)
    • Test auf DOS-Zeilenenden (\r\n anstelle von nur \n)
    • Überprüfung auf Leerzeichen am Ende von Zeilen
    • Test, ob alle zu übersetzenden Strings in
+              locale/de/all vorhanden sind
    • Test, ob alle Webseiten-Templates in
+              templates/webpages mit vom Perl-Modul
+              Template compiliert werden können
    4.6.5.2. Konvention für Verzeichnis- und Dateinamen
    Es gibt momentan eine wenige Richtlinien, wie Test-Scripte zu
+          benennen sind. Bitte die folgenden Punkte als Richtlinie betrachten
+          und ihnen soweit es geht folgen:
    • Die Dateiendung muss .t
+              lauten.
    • Namen sind englisch, komplett klein geschrieben und
+              einzelne Wörter mit Unterstrichten getrennt (beispielsweise
+              bad_function_params.t).
    • Unterverzeichnisse sollten grob nach dem Themenbereich
+              benannt sein, mit dem sich die Scripte darin befassen
+              (beispielsweise background_jobs für Tests
+              rund um Hintergrund-Jobs).
    • Test-Scripte sollten einen überschaubaren Bereich von
+              Funktionalität testen, der logisch zusammenhängend ist (z.B. nur
+              Tests für eine einzelne Funktion in einem Modul). Lieber mehrere
+              Test-Scripte schreiben.
    4.6.5.3. Minimales Skelett für eigene Scripte
    Der folgenden Programmcode enthält das kleinstmögliche
+          Testscript und kann als Ausgangspunkt für eigene Tests verwendet
+          werden:
    use Test::More tests => 0;
 
-  if ($use_modules) {
-    $row->{modules} = MODULE->retrieve(
-      id   => $row->{id},
-      date => $use_now ? localtime() : $row->{time},
-    );
-  }
+use lib 't';
 
-  $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 {
-  ...
-}
+use Support::TestSetup;
 
-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 Operator "?:", 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 kivitendo - 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.

    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 - 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.5. Die kivitendo-Test-Suite Zum Anfang 4.7. Dokumentation erstellen
\ No newline at end of file +Support::TestSetup::login();

Wird eine vollständig initialisierte kivitendo-Umgebung + benötigt (Stichwort: alle globalen Variablen wie + $::auth, $::form oder + $::lxdebug), so muss in der Konfigurationsdatei + config/kivitendo.conf im Abschnitt + testing.login ein gültiger Login-Name eingetragen + sein. Dieser wird für die Datenbankverbindung benötigt.

Wir keine vollständig initialisierte Umgebung benötigt, so + kann die letzte Zeile 

Support::TestSetup::login();

+ weggelassen werden, was die Ausführungszeit des Scripts leicht + verringert.

Zurück Nach oben Weiter
4.5. Translations and languages Zum Anfang 4.7. Stil-Richtlinien
\ No newline at end of file