X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fhtml%2Fch04s06.html;h=10e6018f68e38cf313fcbaeae5414c9b1e5ec6cf;hb=434d7c13b2618f29235e8f7adc93001ae5552915;hp=2c152a51c06a6bc7bc8538be03e5a69c2a286231;hpb=15f021a67aa7e26458a3fbac8efe89ef9c0b0657;p=kivitendo-erp.git diff --git a/doc/html/ch04s06.html b/doc/html/ch04s06.html index 2c152a51c..10e6018f6 100644 --- a/doc/html/ch04s06.html +++ b/doc/html/ch04s06.html @@ -1,39 +1,120 @@ - - 4.6. Dokumentation erstellen
4.6. Dokumentation erstellen
Zurück Kapitel 4. Entwicklerdokumentation 

4.6. Dokumentation erstellen

4.6.1. Einführung

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

4.6.2. Benötigte Software

- 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 Lx-Office übernimmt diese Aufgabe das Shell-Script - scripts/build_doc.sh. -

- Das Script benötigt zur Konvertierung verschiedene Softwarekomponenten, die im normalen Lx-Office-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

4.6.3. PDFs und HTML-Seiten erstellen

- Die eigentliche Konvertierung erfolgt nach Installation der benötigten Software mit einem einfachen Aufruf direkt aus dem - Lx-Office-Installationsverzeichnis heraus: - 

./scripts/build_doc.sh

4.6.4. Einchecken in das Git-Repository

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

Zurück Nach oben 
4.5. Stil-Richtlinien Zum Anfang 
\ No newline at end of file + + 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
+  }
+
+  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 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