Inventory: with_objects cleanup
[kivitendo-erp.git] / doc / html / ch04s07.html
1 <html><head>
2       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
3    <title>4.7. 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 3.5.6.1: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s06.html" title="4.6. Die kivitendo-Test-Suite"><link rel="next" href="ch04s08.html" title="4.8. 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.7. Stil-Richtlinien</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s06.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="ch04s08.html">Weiter</a></td></tr></table><hr></div><div class="sect1" title="4.7. Stil-Richtlinien"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="devel.style-guide"></a>4.7. 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   }
14
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   }
21
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 }
41
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 Operator "?:", 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="ch04s06.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="ch04s08.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.6. Die kivitendo-Test-Suite&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.8. Dokumentation erstellen</td></tr></table></div></body></html>