Projekt

Allgemein

Profil

« Zurück | Weiter » 

Revision d1564e8a

Von Moritz Bunkus vor etwa 12 Jahren hinzugefügt

  • ID d1564e8aa44f920d0c9ddf08141417f0deb89ba6
  • Vorgänger 075be078
  • Nachfolger d00e1b28

Doku: Test-Doku aus t/README in die Haupt-Doku überführt & erweitert

Unterschiede anzeigen:

doc/html/ch04s05.html
1 1
<html><head>
2 2
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
3
   <title>4.5. Stil-Richtlinien</title><link rel="stylesheet" type="text/css" href="style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1-RC2"><link rel="home" href="index.html" title="kivitendo: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s04.html" title="4.4. Translations and languages"><link rel="next" href="ch04s06.html" title="4.6. Dokumentation erstellen"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.5. Stil-Richtlinien</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s04.html">Zurück</a>&nbsp;</td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch04s06.html">Weiter</a></td></tr></table><hr></div><div class="sect1" title="4.5. Stil-Richtlinien"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="devel.style-guide"></a>4.5. Stil-Richtlinien</h2></div></div></div><p>Die folgenden Regeln haben das Ziel, den Code möglichst gut les-
4
      und wartbar zu machen. Dazu gehört zum Einen, dass der Code einheitlich
5
      eingerückt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden
6
      wird (Stichworte "Klammern" oder "Hash-Keys").</p><p>Diese Regeln sind keine Schikane sondern erleichtern allen das
7
      Leben!</p><p>Jeder, der einen Patch schickt, sollte seinen Code vorher
8
      überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere
9
      nicht.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Es werden keine echten Tabs sondern Leerzeichen
10
          verwendet.</p></li><li class="listitem"><p>Die Einrückung beträgt zwei Leerzeichen. Beispiel:</p><pre class="programlisting">foreach my $row (@data) {
11
  if ($flag) {
12
    # do something with $row
13
  }
3
   <title>4.5. Die kivitendo-Test-Suite</title><link rel="stylesheet" type="text/css" href="style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1-RC2"><link rel="home" href="index.html" title="kivitendo: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s04.html" title="4.4. Translations and languages"><link rel="next" href="ch04s06.html" title="4.6. Stil-Richtlinien"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.5. Die kivitendo-Test-Suite</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s04.html">Zurück</a>&nbsp;</td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch04s06.html">Weiter</a></td></tr></table><hr></div><div class="sect1" title="4.5. Die kivitendo-Test-Suite"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="devel.testsuite"></a>4.5. Die kivitendo-Test-Suite</h2></div></div></div><div class="sect2" title="4.5.1. Einführung"><div class="titlepage"><div><div><h3 class="title"><a name="devel.testsuite.intro"></a>4.5.1. Einführung</h3></div></div></div><p>kivitendo enthält eine Suite für automatisierte Tests. Sie basiert auf dem Standard-Perl-Modul <code class="literal">Test::More</code>.</p><p>Die grundlegenden Fakten sind:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Alle Tests liegen im Unterverzeichnis <code class="filename">t/</code>.</p></li><li class="listitem"><p>Ein Script (bzw. ein Test) in <code class="filename">f/</code> enthält einen oder mehrere Testfälle.</p></li><li class="listitem"><p>Alle Dateinamen von Tests enden auf <code class="literal">.t</code>. Es sind selbstständig ausführbare Perl-Scripte.</p></li><li class="listitem"><p>Die Test-Suite besteht aus der Gesamtheit aller Tests, sprich aller Scripte in <code class="filename">f/</code>, deren
4
          Dateiname auf <code class="literal">.t</code> endet.</p></li></ul></div></div><div class="sect2" title="4.5.2. Voraussetzungen"><div class="titlepage"><div><div><h3 class="title"><a name="devel.testsuite.prerequisites"></a>4.5.2. Voraussetzungen</h3></div></div></div><p>Für die Ausführung werden neben den für kivitendo eh schon benötigten Module noch weitere Perl-Module benötigt. Diese sind:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
5
                     <code class="literal">Test::Deep</code> (Debian-Paketname: <code class="literal">libtest-deep-perl</code>; Fedora Core:
6
          <code class="literal">perl-Test-Deep</code>; openSuSE: <code class="literal">perl-Test-Deep</code>)</p></li></ul></div></div><div class="sect2" title="4.5.3. Existierende Tests ausführen"><div class="titlepage"><div><div><h3 class="title"><a name="devel.testsuite.execution"></a>4.5.3. 
7
          Existierende Tests ausführen
8
        </h3></div></div></div><p>Es gibt mehrere Möglichkeiten zum Ausführen der Tests: entweder, man lässt alle Tests auf einmal ausführen, oder man führt
9
        gezielt einzelne Scripte aus. Für beide Fälle gibt es das Helferscript <code class="filename">t/test.sh</code>.</p><p>Will man die komplette Test-Suite ausführen, so muss man einfach nur <code class="filename">t/test.sh</code> ohne weitere Parameter aus
10
        dem kivitendo-Basisverzeichnis heraus ausführen.</p><p>Um einzelne Test-Scripte auszuführen, übergibt man deren Namen an <code class="filename">t/test.sh</code>. Beispielsweise:</p><pre class="programlisting">t/test.sh t/form/format_amount.t t/background_job/known_jobs.t</pre></div><div class="sect2" title="4.5.4. Bedeutung der verschiedenen Test-Scripte"><div class="titlepage"><div><div><h3 class="title"><a name="devel.testsuite.meaning_of_scripts"></a>4.5.4. 
11
          Bedeutung der verschiedenen Test-Scripte
12
        </h3></div></div></div><p>Die Test-Suite umfasst Tests sowohl für Funktionen als auch für Programmierstil. Einige besonders zu erwähnende, weil auch
13
        während der Entwicklung nützliche Tests sind:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
14
                     <code class="filename">t/001compile.t</code> -- compiliert alle Quelldateien und bricht bei Fehlern sofort ab</p></li><li class="listitem"><p>
15
                     <code class="filename">t/002goodperl.t</code> -- überprüft alle Perl-Dateien auf Anwesenheit von '<code class="literal">use strict</code>'-Anweisungen</p></li><li class="listitem"><p>
16
                     <code class="filename">t/003safesys.t</code> -- überprüft Aufrufe von <code class="function">system()</code> und <code class="function">exec()</code> auf Gültigkeit</p></li><li class="listitem"><p>
17
                     <code class="filename">t/005no_tabs.t</code> -- überprüft, ob Dateien Tab-Zeichen enthalten</p></li><li class="listitem"><p>
18
                     <code class="filename">t/006spelling.t</code> -- sucht nach häufigen Rechtschreibfehlern</p></li><li class="listitem"><p>
19
                     <code class="filename">t/011pod.t</code> -- überprüft die Syntax von Dokumentation im POD-Format auf Gültigkeit</p></li></ul></div><p>Weitere Test-Scripte überprüfen primär die Funktionsweise einzelner Funktionen und Module.</p></div><div class="sect2" title="4.5.5. Neue Test-Scripte erstellen"><div class="titlepage"><div><div><h3 class="title"><a name="devel.testsuite.create_new"></a>4.5.5. 
20
          Neue Test-Scripte erstellen
21
        </h3></div></div></div><p>Es wird sehr gern gesehen, wenn neue Funktionalität auch gleich mit einem Test-Script abgesichert wird. Auch bestehende
22
        Funktion darf und soll ausdrücklich nachträglich mit Test-Scripten abgesichert werden.</p><div class="sect3" title="4.5.5.1. Ideen für neue Test-Scripte, die keine konkreten Funktionen testen"><div class="titlepage"><div><div><h4 class="title"><a name="devel.testsuite.ideas_for_non_function_tests"></a>4.5.5.1. 
23
            Ideen für neue Test-Scripte, die keine konkreten Funktionen testen
24
          </h4></div></div></div><p> Ideen, die abgesehen von Funktions noch nicht umgesetzt wurden:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Überprüfung auf fehlende symbolische Links</p></li><li class="listitem"><p>Suche nach Nicht-ASCII-Zeichen in Perl-Code-Dateien (mit gewissen Einschränkungen wie das Erlauben von deutschen Umlauten)</p></li><li class="listitem"><p>Test auf DOS-Zeilenenden (\r\n anstelle von nur \n)</p></li><li class="listitem"><p>Überprüfung auf Leerzeichen am Ende von Zeilen</p></li><li class="listitem"><p>Test, ob alle zu übersetzenden Strings in <code class="filename">locale/de/all</code> vorhanden sind</p></li><li class="listitem"><p>Test, ob alle Webseiten-Templates in <code class="filename">templates/webpages</code> mit vom Perl-Modul <code class="literal">Template</code> compiliert werden können</p></li></ul></div></div><div class="sect3" title="4.5.5.2. Konvention für Verzeichnis- und Dateinamen"><div class="titlepage"><div><div><h4 class="title"><a name="devel.testsuite.directory_and_test_names"></a>4.5.5.2. 
25
            Konvention für Verzeichnis- und Dateinamen
26
          </h4></div></div></div><p>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:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Die Dateiendung muss <code class="filename">.t</code> lauten.</p></li><li class="listitem"><p>Namen sind englisch, komplett klein geschrieben und einzelne Wörter mit Unterstrichten getrennt (beispielsweise
27
            <code class="filename">bad_function_params.t</code>).</p></li><li class="listitem"><p>Unterverzeichnisse sollten grob nach dem Themenbereich benannt sind, mit dem sich die Scripte darin befassen
28
            (beispielsweise <code class="filename">background_jobs</code> für Tests rund um Hintergrund-Jobs).</p></li><li class="listitem"><p>Test-Scripte sollten einen überschaubaren Bereich von Funktionalität testen, der logisch zusammenhängend ist
29
            (z.B. nur Tests für eine einzelne Funktion in einem Modul). Lieber mehrere Test-Scripte schreiben.</p></li></ul></div></div><div class="sect3" title="4.5.5.3. Minimales Skelett für eigene Scripte"><div class="titlepage"><div><div><h4 class="title"><a name="devel.testsuite.minimal_example"></a>4.5.5.3. 
30
            Minimales Skelett für eigene Scripte
31
          </h4></div></div></div><p>Der folgenden Programmcode enthält das kleinstmögliche Testscript und kann als Ausgangspunkt für eigene Tests verwendet werden:</p><pre class="programlisting">use Test::More tests =&gt; 0;
14 32

  
15
  if ($use_modules) {
16
    $row-&gt;{modules} = MODULE-&gt;retrieve(
17
      id   =&gt; $row-&gt;{id},
18
      date =&gt; $use_now ? localtime() : $row-&gt;{time},
19
    );
20
  }
33
use lib 't';
21 34

  
22
  $report-&gt;add($row);
23
}</pre></li><li class="listitem"><p>Öffnende geschweifte Klammern befinden sich auf der gleichen
24
          Zeile wie der letzte Befehl. Beispiele:</p><pre class="programlisting">sub debug {
25
  ...
26
}</pre><p>oder</p><pre class="programlisting">if ($form-&gt;{item_rows} &gt; 0) {
27
  ...
28
}</pre></li><li class="listitem"><p>Schließende geschweifte Klammern sind so weit eingerückt wie
29
          der Befehl / die öffnende schließende Klammer, die den Block
30
          gestartet hat, und nicht auf der Ebene des Inhalts. Die gleichen
31
          Beispiele wie bei 3. gelten.</p></li><li class="listitem"><p>Die Wörter "<code class="function">else</code>",
32
          "<code class="function">elsif</code>", "<code class="function">while</code>" befinden
33
          sich auf der gleichen Zeile wie schließende geschweifte Klammern.
34
          Beispiele:</p><pre class="programlisting">if ($form-&gt;{sum} &gt; 1000) {
35
  ...
36
} elsif ($form-&gt;{sum} &gt; 0) {
37
  ...
38
} else {
39
  ...
40
}
35
use Support::TestSetup;
41 36

  
42
do {
43
  ...
44
} until ($a &gt; 0);</pre></li><li class="listitem"><p>Parameter von Funktionsaufrufen müssen mit runden Klammern
45
          versehen werden. Davon nicht betroffen sind interne Perl-Funktionen,
46
          und grep-ähnliche Operatoren. Beispiel:</p><pre class="programlisting">$main::lxdebug-&gt;message("Could not find file.");
47
%options = map { $_ =&gt; 1 } grep { !/^#/ } @config_file;</pre></li><li class="listitem"><p>Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:</p><p>Generell gilt: Hashkeys und Arrayindices sollten nicht durch
48
          Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig,
49
          Blöcke schon. Beispiel:</p><pre class="programlisting">if (($form-&gt;{debug} == 1) &amp;&amp; ($form-&gt;{sum} - 100 &lt; 0)) {
50
  ...
51
}
52

  
53
$array[$i + 1]             = 4;
54
$form-&gt;{sum}              += $form-&gt;{"row_$i"};
55
$form-&gt;{ $form-&gt;{index} } += 1;
56

  
57
map { $form-&gt;{sum} += $form-&gt;{"row_$_"} } 1..$rowcount;</pre></li><li class="listitem"><p>Mehrzeilige Befehle</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Werden die Parameter eines Funktionsaufrufes auf mehrere
58
              Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerückt
59
              werden, in der die ersten Funktionsparameter in der ersten Zeile
60
              stehen. Beispiel:</p><pre class="programlisting">$sth = $dbh-&gt;prepare("SELECT * FROM some_table WHERE col = ?",
61
                    $form-&gt;{some_col_value});</pre></li><li class="listitem"><p>Ein Spezialfall ist der ternäre Oprator "?:", der am
62
              besten in einer übersichtlichen Tabellenstruktur organisiert
63
              wird. Beispiel:</p><pre class="programlisting">my $rowcount = $form-&gt;{"row_$i"} ? $i
64
             : $form-&gt;{oldcount} ? $form-&gt;{oldcount} + 1
65
             :                     $form-&gt;{rowcount} - $form-&gt;{rowbase};</pre></li></ol></div></li><li class="listitem"><p>Kommentare</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Kommentare, die alleine in einer Zeile stehen, sollten
66
              soweit wie der Code eingerückt sein.</p></li><li class="listitem"><p>Seitliche hängende Kommentare sollten einheitlich
67
              formatiert werden.</p></li><li class="listitem"><p>Sämtliche Kommentare und Sonstiges im Quellcode ist bitte
68
              auf Englisch zu verfassen. So wie ich keine Lust habe,
69
              französischen Quelltext zu lesen, sollte auch der kivitendo
70
              Quelltext für nicht-Deutschsprachige lesbar sein.
71
              Beispiel:</p><pre class="programlisting">my $found = 0;
72
while (1) {
73
  last if $found;
74

  
75
  # complicated check
76
  $found = 1 if //
77
}
78

  
79
$i  = 0        # initialize $i
80
$n  = $i;      # save $i
81
$i *= $const;  # do something crazy
82
$i  = $n;      # recover $i</pre></li></ol></div></li><li class="listitem"><p>Hashkeys sollten nur in Anführungszeichen stehen, wenn die
83
          Interpolation gewünscht ist. Beispiel:</p><pre class="programlisting">$form-&gt;{sum}      = 0;
84
$form-&gt;{"row_$i"} = $form-&gt;{"row_$i"} - 5;
85
$some_hash{42}    = 54;</pre></li><li class="listitem"><p>Die maximale Zeilenlänge ist nicht beschränkt. Zeilenlängen
86
          unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber
87
          wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in
88
          grossen Tabellen), dann ist Lesbarkeit vorzuziehen.</p><p>Als Beispiel sei die Funktion
89
          <code class="function">print_options</code> aus
90
          <code class="filename">bin/mozilla/io.pl</code> angeführt.</p></li><li class="listitem"><p>Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind
91
          unerwünscht. Sie führen zu unnötigen Whitespaceänderungen, die diffs
92
          verfälschen.</p><p>Emacs und vim haben beide recht einfache Methoden zur
93
          Entfernung von trailing whitespace. Emacs kennt das Kommande
94
          <span class="command"><strong>nuke-trailing-whitespace</strong></span>, vim macht das gleiche
95
          manuell über <code class="literal">:%s/\s\+$//e</code> Mit <code class="literal">:au
96
          BufWritePre * :%s/\s\+$//e</code> wird das an Speichern
97
          gebunden.</p></li><li class="listitem"><p>Es wird kein <span class="command"><strong>perltidy</strong></span> verwendet.</p><p>In der Vergangenheit wurde versucht,
98
          <span class="command"><strong>perltidy</strong></span> zu verwenden, um einen einheitlichen
99
          Stil zu erlangen. Es hat sich aber gezeigt, dass
100
          <span class="command"><strong>perltidy</strong></span>s sehr eigenwilliges Verhalten, was
101
          Zeilenumbrüche angeht, oftmals gut formatierten Code zerstört. Für
102
          den Interessierten sind hier die
103
          <span class="command"><strong>perltidy</strong></span>-Optionen, die grob den beschriebenen
104
          Richtlinien entsprechen:</p><pre class="programlisting">-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
105
-aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
106
-lp -vt=1 -vtc=1</pre></li><li class="listitem"><p>
107
                  <code class="varname">STDERR</code> ist tabu. Unkonditionale
108
          Debugmeldungen auch.</p><p>kivitendo bietet mit dem Modul <code class="classname">LXDebug</code>
109
          einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen
110
          Grund, nach <code class="varname">STDERR</code> zu schreiben.</p><p>Die <code class="classname">LXDebug</code>-Methode
111
          "<code class="function">message</code>" nimmt als ersten Paramter außerdem
112
          eine Flagmaske, für die die Meldung angezeigt wird, wobei "0" immer
113
          angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden
114
          und werden in den meisten Fällen auch vom Repository
115
          zurückgewiesen.</p></li><li class="listitem"><p>Alle neuen Module müssen use strict verwenden.</p><p>
116
                  <code class="varname">$form</code>, <code class="varname">$auth</code>,
117
          <code class="varname">$locale</code>, <code class="varname">$lxdebug</code> und
118
          <code class="varname">%myconfig</code> werden derzeit aus dem main package
119
          importiert (siehe <a class="xref" href="ch04.html#devel.globals" title="4.1. Globale Variablen">Globale Variablen</a>. Alle anderen
120
          Konstrukte sollten lexikalisch lokal gehalten werden.</p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s04.html">Zurück</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Nach oben</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch04s06.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.4. Translations and languages&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top">&nbsp;4.6. Dokumentation erstellen</td></tr></table></div></body></html>
37
Support::TestSetup::login();</pre><p>Wird eine vollständig initialisierte kivitendo-Umgebung benötigt (Stichwort: alle globalen Variablen wie
38
          <code class="varname">$::auth</code>, <code class="varname">$::form</code> oder <code class="varname">$::lxdebug</code>), so muss in der Konfigurationsdatei
39
          <code class="filename">config/kivitendo.conf</code> im Abschnitt <code class="literal">testing.login</code> ein gültiger Login-Name eingetragen
40
          sein. Dieser wird für die Datenbankverbindung benötigt.</p><p>Wir keine vollständig initialisierte Umgebung benötigt, so kann die letzte Zeile <code class="code">Support::TestSetup::login();</code>
41
          weggelassen werden, was die Ausführungszeit des Scripts leicht verringert.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s04.html">Zurück</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Nach oben</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch04s06.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.4. Translations and languages&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top">&nbsp;4.6. Stil-Richtlinien</td></tr></table></div></body></html>

Auch abrufbar als: Unified diff