X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fhtml%2Fch04s07.html;h=c1e0dd873e9769b860ae688fdad72946f67fd1d4;hb=53593baa211863fbf66540cf1bcc36c8fb37257f;hp=bfa530d64919904f4d75ee63696ae639812560dd;hpb=25fc5ea45083477a254b3dc4226661551bfab847;p=kivitendo-erp.git diff --git a/doc/html/ch04s07.html b/doc/html/ch04s07.html index bfa530d64..c1e0dd873 100644 --- a/doc/html/ch04s07.html +++ b/doc/html/ch04s07.html @@ -1,38 +1,120 @@
-Diese Dokumentation ist in DocBook⢠- XML geschrieben. Zum Bearbeiten reicht grundsätzlich ein Text-Editor. - Mehr Komfort bekommt man, wenn man einen dedizierten XML-fähigen - Editor nutzt, der spezielle Unterstützung für - DocBook⢠mitbringt. Wir empfehlen dafür den - XMLmind XML - Editor, der bei nicht kommerzieller Nutzung kostenlos - ist.
Bei DocBook⢠ist Prinzip, dass - ausschlieÃlich die XML-Quelldatei bearbeitet wird. Aus dieser werden - dann mit entsprechenden Stylesheets andere Formate wie PDF oder HTML - erzeugt. Bei kivitendo übernimmt diese Aufgabe das Shell-Script - scripts/build_doc.sh.
Das Script benötigt zur Konvertierung verschiedene - Softwarekomponenten, die im normalen kivitendo-Betrieb nicht benötigt - werden:
- Java - in einer halbwegs aktuellen Version
Das Java-Build-System Apache Ant -
Das Dokumentations-System Dobudish für
- DocBook⢠4.5, eine Zusammenstellung
- diverser Stylesheets und Grafiken zur Konvertierung von
- DocBook⢠XML in andere Formate. Das
- Paket, das benötigt wird, ist zum Zeitpunkt der
- Dokumentationserstellung
- dobudish-nojre-1.1.4.zip
, aus auf code.google.com
- bereitsteht.
Apache Ant sowie ein dazu passendes Java Runtime Environment - sind auf allen gängigen Plattformen verfügbar. Beispiel für - Debian/Ubuntu:
apt-get install ant openjdk-7-jre
Nach dem Download von Dobudish muss Dobudish im Unterverzeichnis
- doc/build
entpackt werden. Beispiel unter der
- Annahme, das Dobudish⢠in
- $HOME/Downloads
heruntergeladen wurde:
cd doc/build -unzip $HOME/Downloads/dobudish-nojre-1.1.4.zip
Die eigentliche Konvertierung erfolgt nach Installation der - benötigten Software mit einem einfachen Aufruf direkt aus dem - kivitendo-Installationsverzeichnis heraus:
./scripts/build_doc.sh
Sowohl die XML-Datei als auch die erzeugten PDF- und - HTML-Dateien sind Bestandteil des Git-Repositories. Daraus folgt, dass - nach Ãnderungen am XML die PDF- und HTML-Dokumente ebenfalls gebaut - und alles zusammen in einem Commit eingecheckt werden sollten.
Die "dobudish
"-Verzeichnisse bzw.
- symbolischen Links gehören hingegen nicht in das Repository.
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 + } + + if ($use_modules) { + $row->{modules} = MODULE->retrieve( + id => $row->{id}, + date => $use_now ? localtime() : $row->{time}, + ); + } + + $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 { + ... +} + +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 $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 + 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, 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.
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.