Projekt

Allgemein

Profil

« Zurück | Weiter » 

Revision 3adb0cb7

Von Moritz Bunkus vor fast 13 Jahren hinzugefügt

  • ID 3adb0cb772af4bcdbd867b5688b3e02356a2e613
  • Vorgänger c4184d54
  • Nachfolger 1c103b3a

doc/skr04-update-3804 nach DocBook gewandelt

Unterschiede anzeigen:

doc/html/ch04s05.html
1 1
<html><head>
2 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) {
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>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) {
16 11
  if ($flag) {
17 12
    # do something with $row
18 13
  }
......
25 20
  }
26 21

  
27 22
  $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 {
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 {
29 25
  ...
30 26
}</pre><p>oder</p><pre class="programlisting">if ($form-&gt;{item_rows} &gt; 0) {
31 27
  ...
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) {
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) {
39 35
  ...
40 36
} elsif ($form-&gt;{sum} &gt; 0) {
41 37
  ...
......
45 41

  
46 42
do {
47 43
  ...
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)) {
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)) {
58 50
  ...
59 51
}
60 52

  
......
62 54
$form-&gt;{sum}              += $form-&gt;{"row_$i"};
63 55
$form-&gt;{ $form-&gt;{index} } += 1;
64 56

  
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
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
75 64
             : $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;
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 Lx-Office
70
              Quelltext f?r nicht-Deutschsprachige lesbar sein.
71
              Beispiel:</p><pre class="programlisting">my $found = 0;
82 72
while (1) {
83 73
  last if $found;
84 74

  
......
89 79
$i  = 0        # initialize $i
90 80
$n  = $i;      # save $i
91 81
$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;
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;
95 84
$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 beschr?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
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
116 105
-aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
117 106
-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>
107
                  <code class="varname">STDERR</code> ist tabu. Unkonditionale
108
          Debugmeldungen auch.</p><p>Lx-Office 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>

Auch abrufbar als: Unified diff