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