doc/html/ch04s05.html

   1 <html><head>
   2       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   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="Lx-Office: 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>
   4        Die folgenden Regeln haben das Ziel, den Code möglichst gut les- und wartbar zu machen. Dazu gehört zum Einen, dass der Code
   5        einheitlich eingerückt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden wird (Stichworte "Klammern" oder "Hash-Keys").
   6       </p><p>
   7        Diese Regeln sind keine Schikane sondern erleichtern allen das Leben!
   8       </p><p>
   9        Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere
  10        nicht.
  11       </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
  12          Es werden keine echten Tabs sondern Leerzeichen verwendet.
  13         </p></li><li class="listitem"><p>
  14          Die Einrückung beträgt zwei Leerzeichen. Beispiel:
  15         </p><pre class="programlisting">foreach my $row (@data) {
  16   if ($flag) {
  17     # do something with $row
  18   }
  19
  20   if ($use_modules) {
  21     $row-&gt;{modules} = MODULE-&gt;retrieve(
  22       id   =&gt; $row-&gt;{id},
  23       date =&gt; $use_now ? localtime() : $row-&gt;{time},
  24     );
  25   }
  26
  27   $report-&gt;add($row);
  28 }</pre></li><li class="listitem"><p>Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie der letzte Befehl. Beispiele:</p><pre class="programlisting">sub debug {
  29   ...
  30 }</pre><p>oder</p><pre class="programlisting">if ($form-&gt;{item_rows} &gt; 0) {
  31   ...
  32 }</pre></li><li class="listitem"><p>
  33          Schließende geschweifte Klammern sind so weit eingerückt wie der Befehl / die öffnende schließende Klammer, die den Block gestartet
  34          hat, und nicht auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten.
  35         </p></li><li class="listitem"><p>
  36          Die Wörter "<code class="function">else</code>", "<code class="function">elsif</code>", "<code class="function">while</code>" befinden sich auf der gleichen
  37          Zeile wie schließende geschweifte Klammern. Beispiele:
  38         </p><pre class="programlisting">if ($form-&gt;{sum} &gt; 1000) {
  39   ...
  40 } elsif ($form-&gt;{sum} &gt; 0) {
  41   ...
  42 } else {
  43   ...
  44 }
  45
  46 do {
  47   ...
  48 } until ($a &gt; 0);</pre></li><li class="listitem"><p>
  49          Parameter von Funktionsaufrufen müssen mit runden Klammern versehen werden. Davon nicht betroffen sind interne Perl-Funktionen,
  50          und grep-ähnliche Operatoren. Beispiel:
  51         </p><pre class="programlisting">$main::lxdebug-&gt;message("Could not find file.");
  52 %options = map { $_ =&gt; 1 } grep { !/^#/ } @config_file;</pre></li><li class="listitem"><p>
  53          Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:
  54         </p><p>
  55          Generell gilt: Hashkeys und Arrayindices sollten nicht durch Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig,
  56          Blöcke schon. Beispiel:
  57         </p><pre class="programlisting">if (($form-&gt;{debug} == 1) &amp;&amp; ($form-&gt;{sum} - 100 &lt; 0)) {
  58   ...
  59 }
  60
  61 $array[$i + 1]             = 4;
  62 $form-&gt;{sum}              += $form-&gt;{"row_$i"};
  63 $form-&gt;{ $form-&gt;{index} } += 1;
  64
  65 map { $form-&gt;{sum} += $form-&gt;{"row_$_"} } 1..$rowcount;</pre></li><li class="listitem"><p>
  66          Mehrzeilige Befehle
  67         </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
  68            Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerückt
  69            werden, in der die ersten Funktionsparameter in der ersten Zeile stehen. Beispiel:
  70           </p><pre class="programlisting">$sth = $dbh-&gt;prepare("SELECT * FROM some_table WHERE col = ?",
  71                     $form-&gt;{some_col_value});</pre></li><li class="listitem"><p>
  72            Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer übersichtlichen Tabellenstruktur organisiert
  73            wird. Beispiel:
  74           </p><pre class="programlisting">my $rowcount = $form-&gt;{"row_$i"} ? $i
  75              : $form-&gt;{oldcount} ? $form-&gt;{oldcount} + 1
  76              :                     $form-&gt;{rowcount} - $form-&gt;{rowbase};</pre></li></ol></div></li><li class="listitem"><p>
  77          Kommentare
  78         </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der Code eingerückt sein.</p></li><li class="listitem"><p>Seitliche hängende Kommentare sollten einheitlich formatiert werden.</p></li><li class="listitem"><p>
  79            Sämtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch zu verfassen. So wie ich keine Lust habe, französischen
  80            Quelltext zu lesen, sollte auch der Lx-Office Quelltext für nicht-Deutschsprachige lesbar sein. Beispiel:
  81           </p><pre class="programlisting">my $found = 0;
  82 while (1) {
  83   last if $found;
  84
  85   # complicated check
  86   $found = 1 if //
  87 }
  88
  89 $i  = 0        # initialize $i
  90 $n  = $i;      # save $i
  91 $i *= $const;  # do something crazy
  92 $i  = $n;      # recover $i</pre></li></ol></div></li><li class="listitem"><p>
  93          Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation gewünscht ist. Beispiel:
  94         </p><pre class="programlisting">$form-&gt;{sum}      = 0;
  95 $form-&gt;{"row_$i"} = $form-&gt;{"row_$i"} - 5;
  96 $some_hash{42}    = 54;</pre></li><li class="listitem"><p>
  97          Die maximale Zeilenlänge ist nicht bescränkt. Zeilenlängen unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber
  98          wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann ist Lesbarkeit vorzuziehen.
  99         </p><p>
 100          Als Beispiel sei die Funktion <code class="function">print_options</code> aus <code class="filename">bin/mozilla/io.pl</code> angeführt.
 101         </p></li><li class="listitem"><p>
 102          Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerwünscht. Sie führen zu unnötigen Whitespaceänderungen, die
 103          diffs verfälschen.
 104         </p><p>
 105          Emacs und vim haben beide recht einfache Methoden zur Entfernung von trailing whitespace. Emacs kennt das Kommande
 106          <span class="command"><strong>nuke-trailing-whitespace</strong></span>, vim macht das gleiche manuell über <code class="literal">:%s/\s\+$//e</code> Mit <code class="literal">:au
 107          BufWritePre * :%s/\s\+$//e</code> wird das an Speichern gebunden.
 108         </p></li><li class="listitem"><p>
 109          Es wird kein <span class="command"><strong>perltidy</strong></span> verwendet.
 110         </p><p>
 111          In der Vergangenheit wurde versucht, <span class="command"><strong>perltidy</strong></span> zu verwenden, um einen einheitlichen Stil zu erlangen. Es hat
 112          sich aber gezeigt, dass <span class="command"><strong>perltidy</strong></span>s sehr eigenwilliges Verhalten, was Zeilenumbrüche angeht, oftmals gut
 113          formatierten Code zerstört. Für den Interessierten sind hier die <span class="command"><strong>perltidy</strong></span>-Optionen, die grob den
 114          beschriebenen Richtlinien entsprechen:
 115         </p><pre class="programlisting">-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
 116 -aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
 117 -lp -vt=1 -vtc=1</pre></li><li class="listitem"><p>
 118
 119                   <code class="varname">STDERR</code> ist tabu. Unkonditionale Debugmeldungen auch.
 120         </p><p>
 121          Lx-Office bietet mit dem Modul <code class="classname">LXDebug</code> einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen
 122          Grund, nach <code class="varname">STDERR</code> zu schreiben.
 123         </p><p>
 124          Die <code class="classname">LXDebug</code>-Methode "<code class="function">message</code>" nimmt als ersten Paramter außerdem eine Flagmaske, für
 125          die die Meldung angezeigt wird, wobei "0" immer angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden und werden in
 126          den meisten Fällen auch vom Repository zurückgewiesen.
 127         </p></li><li class="listitem"><p>
 128          Alle neuen Module müssen use strict verwenden.
 129         </p><p>
 130
 131                   <code class="varname">$form</code>, <code class="varname">$auth</code>, <code class="varname">$locale</code>, <code class="varname">$lxdebug</code> und
 132          <code class="varname">%myconfig</code> werden derzeit aus dem main package importiert (siehe <a class="xref" href="ch04.html#devel.globals" title="4.1. Globale Variablen">Globale Variablen</a>. Alle anderen
 133          Konstrukte sollten lexikalisch lokal gehalten werden.
 134         </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>