X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;ds=sidebyside;f=doc%2Fhtml%2Fch04s06.html;h=6ef670f9a1c5176d57af493efd4d3402cd2494a1;hb=8da82ce0e57e5ae5a05f4fec2dea1fb049aadf10;hp=45056db4e0b56d608b508b1d9459893d72e0a264;hpb=b8a5c5916dd07fbe14156e6e4f688b1f7ca9ddb2;p=kivitendo-erp.git diff --git a/doc/html/ch04s06.html b/doc/html/ch04s06.html index 45056db4e..6ef670f9a 100644 --- a/doc/html/ch04s06.html +++ b/doc/html/ch04s06.html @@ -1,120 +1,115 @@
-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.
Es werden keine echten Tabs sondern Leerzeichen - verwendet.
Die Einrückung beträgt zwei Leerzeichen. Beispiel:
foreach my $row (@data) { - if ($flag) { - # do something with $row - } +4.6. Die kivitendo-Test-Suite 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.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.
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.tDie 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()
undexec()
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ültigkeitWeitere Test-Scripte überprüfen primär die Funktionsweise + einzelner Funktionen und Module.
\ No newline at end of file +Support::TestSetup::login();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.
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 sindTest, ob alle Webseiten-Templates in +
templates/webpages
mit vom Perl-Modul +Template
compiliert werden könnenEs 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.
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); -}Ãffnende geschweifte Klammern befinden sich auf der gleichen - Zeile wie der letzte Befehl. Beispiele:
sub debug { - ... -}oder
if ($form->{item_rows} > 0) { - ... -}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.
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);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;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;Mehrzeilige Befehle
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});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};Kommentare
Kommentare, die alleine in einer Zeile stehen, sollten - soweit wie der Code eingerückt sein.
Seitliche hängende Kommentare sollten einheitlich - formatiert werden.
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 $iHashkeys 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 - 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 - 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.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-
STDERR
ist tabu. Unkonditionale - Debugmeldungen auch.kivitendo bietet mit dem Modul
LXDebug
- einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen - Grund, nachSTDERR
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.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.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.