Projekt

Allgemein

Profil

« Zurück | Weiter » 

Revision 3adb0cb7

Von Moritz Bunkus vor etwa 13 Jahren hinzugefügt

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

doc/skr04-update-3804 nach DocBook gewandelt

Unterschiede anzeigen:

doc/html/ch04s05.html
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<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- und wartbar zu machen. Dazu geh?rt zum Einen, dass der Code
einheitlich einger?ckt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden wird (Stichworte "Klammern" oder "Hash-Keys").
</p><p>
Diese Regeln sind keine Schikane sondern erleichtern allen das Leben!
</p><p>
Jeder, der einen Patch schickt, sollte seinen Code vorher ?berpr?fen. Einige der Regeln lassen sich automatisch ?berpr?fen, andere
nicht.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Es werden keine echten Tabs sondern Leerzeichen verwendet.
</p></li><li class="listitem"><p>
Die Einr?ckung betr?gt zwei Leerzeichen. Beispiel:
</p><pre class="programlisting">foreach my $row (@data) {
<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-
und wartbar zu machen. Dazu geh?rt zum Einen, dass der Code einheitlich
einger?ckt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden
wird (Stichworte "Klammern" oder "Hash-Keys").</p><p>Diese Regeln sind keine Schikane sondern erleichtern allen das
Leben!</p><p>Jeder, der einen Patch schickt, sollte seinen Code vorher
?berpr?fen. Einige der Regeln lassen sich automatisch ?berpr?fen, andere
nicht.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Es werden keine echten Tabs sondern Leerzeichen
verwendet.</p></li><li class="listitem"><p>Die Einr?ckung betr?gt zwei Leerzeichen. Beispiel:</p><pre class="programlisting">foreach my $row (@data) {
if ($flag) {
# do something with $row
}
......
}
$report-&gt;add($row);
}</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 {
}</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 {
...
}</pre><p>oder</p><pre class="programlisting">if ($form-&gt;{item_rows} &gt; 0) {
...
}</pre></li><li class="listitem"><p>
Schlie?ende geschweifte Klammern sind so weit einger?ckt wie der Befehl / die ?ffnende schlie?ende Klammer, die den Block gestartet
hat, und nicht auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten.
</p></li><li class="listitem"><p>
Die W?rter "<code class="function">else</code>", "<code class="function">elsif</code>", "<code class="function">while</code>" befinden sich auf der gleichen
Zeile wie schlie?ende geschweifte Klammern. Beispiele:
</p><pre class="programlisting">if ($form-&gt;{sum} &gt; 1000) {
}</pre></li><li class="listitem"><p>Schlie?ende geschweifte Klammern sind so weit einger?ckt wie
der Befehl / die ?ffnende schlie?ende Klammer, die den Block
gestartet hat, und nicht auf der Ebene des Inhalts. Die gleichen
Beispiele wie bei 3. gelten.</p></li><li class="listitem"><p>Die W?rter "<code class="function">else</code>",
"<code class="function">elsif</code>", "<code class="function">while</code>" befinden
sich auf der gleichen Zeile wie schlie?ende geschweifte Klammern.
Beispiele:</p><pre class="programlisting">if ($form-&gt;{sum} &gt; 1000) {
...
} elsif ($form-&gt;{sum} &gt; 0) {
...
......
do {
...
} until ($a &gt; 0);</pre></li><li class="listitem"><p>
Parameter von Funktionsaufrufen m?ssen mit runden Klammern versehen werden. Davon nicht betroffen sind interne Perl-Funktionen,
und grep-?hnliche Operatoren. Beispiel:
</p><pre class="programlisting">$main::lxdebug-&gt;message("Could not find file.");
%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 Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig,
Bl?cke schon. Beispiel:
</p><pre class="programlisting">if (($form-&gt;{debug} == 1) &amp;&amp; ($form-&gt;{sum} - 100 &lt; 0)) {
} until ($a &gt; 0);</pre></li><li class="listitem"><p>Parameter von Funktionsaufrufen m?ssen mit runden Klammern
versehen werden. Davon nicht betroffen sind interne Perl-Funktionen,
und grep-?hnliche Operatoren. Beispiel:</p><pre class="programlisting">$main::lxdebug-&gt;message("Could not find file.");
%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
Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig,
Bl?cke schon. Beispiel:</p><pre class="programlisting">if (($form-&gt;{debug} == 1) &amp;&amp; ($form-&gt;{sum} - 100 &lt; 0)) {
...
}
......
$form-&gt;{sum} += $form-&gt;{"row_$i"};
$form-&gt;{ $form-&gt;{index} } += 1;
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 Zeilen aufgeteilt, so sollten diese bis zu der Spalte einger?ckt
werden, in der die ersten Funktionsparameter in der ersten Zeile stehen. Beispiel:
</p><pre class="programlisting">$sth = $dbh-&gt;prepare("SELECT * FROM some_table WHERE col = ?",
$form-&gt;{some_col_value});</pre></li><li class="listitem"><p>
Ein Spezialfall ist der tern?re Oprator "?:", der am besten in einer ?bersichtlichen Tabellenstruktur organisiert
wird. Beispiel:
</p><pre class="programlisting">my $rowcount = $form-&gt;{"row_$i"} ? $i
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
Zeilen aufgeteilt, so sollten diese bis zu der Spalte einger?ckt
werden, in der die ersten Funktionsparameter in der ersten Zeile
stehen. Beispiel:</p><pre class="programlisting">$sth = $dbh-&gt;prepare("SELECT * FROM some_table WHERE col = ?",
$form-&gt;{some_col_value});</pre></li><li class="listitem"><p>Ein Spezialfall ist der tern?re Oprator "?:", der am
besten in einer ?bersichtlichen Tabellenstruktur organisiert
wird. Beispiel:</p><pre class="programlisting">my $rowcount = $form-&gt;{"row_$i"} ? $i
: $form-&gt;{oldcount} ? $form-&gt;{oldcount} + 1
: $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 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>
S?mtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch zu verfassen. So wie ich keine Lust habe, franz?sischen
Quelltext zu lesen, sollte auch der Lx-Office Quelltext f?r nicht-Deutschsprachige lesbar sein. Beispiel:
</p><pre class="programlisting">my $found = 0;
: $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
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>S?mtliche Kommentare und Sonstiges im Quellcode ist bitte
auf Englisch zu verfassen. So wie ich keine Lust habe,
franz?sischen Quelltext zu lesen, sollte auch der Lx-Office
Quelltext f?r nicht-Deutschsprachige lesbar sein.
Beispiel:</p><pre class="programlisting">my $found = 0;
while (1) {
last if $found;
......
$i = 0 # initialize $i
$n = $i; # save $i
$i *= $const; # do something crazy
$i = $n; # recover $i</pre></li></ol></div></li><li class="listitem"><p>
Hashkeys sollten nur in Anf?hrungszeichen stehen, wenn die Interpolation gew?nscht ist. Beispiel:
</p><pre class="programlisting">$form-&gt;{sum} = 0;
$i = $n; # recover $i</pre></li></ol></div></li><li class="listitem"><p>Hashkeys sollten nur in Anf?hrungszeichen stehen, wenn die
Interpolation gew?nscht ist. Beispiel:</p><pre class="programlisting">$form-&gt;{sum} = 0;
$form-&gt;{"row_$i"} = $form-&gt;{"row_$i"} - 5;
$some_hash{42} = 54;</pre></li><li class="listitem"><p>
Die maximale Zeilenl?nge ist nicht beschr?nkt. Zeilenl?ngen unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber
wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann ist Lesbarkeit vorzuziehen.
</p><p>
Als Beispiel sei die Funktion <code class="function">print_options</code> aus <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 unerw?nscht. Sie f?hren zu unn?tigen Whitespace?nderungen, die
diffs verf?lschen.
</p><p>
Emacs und vim haben beide recht einfache Methoden zur Entfernung von trailing whitespace. Emacs kennt das Kommande
<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
BufWritePre * :%s/\s\+$//e</code> wird das an Speichern 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, <span class="command"><strong>perltidy</strong></span> zu verwenden, um einen einheitlichen Stil zu erlangen. Es hat
sich aber gezeigt, dass <span class="command"><strong>perltidy</strong></span>s sehr eigenwilliges Verhalten, was Zeilenumbr?che angeht, oftmals gut
formatierten Code zerst?rt. F?r den Interessierten sind hier die <span class="command"><strong>perltidy</strong></span>-Optionen, die grob den
beschriebenen Richtlinien entsprechen:
</p><pre class="programlisting">-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
$some_hash{42} = 54;</pre></li><li class="listitem"><p>Die maximale Zeilenl?nge ist nicht beschr?nkt. Zeilenl?ngen
unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber
wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in
grossen Tabellen), dann ist Lesbarkeit vorzuziehen.</p><p>Als Beispiel sei die Funktion
<code class="function">print_options</code> aus
<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
unerw?nscht. Sie f?hren zu unn?tigen Whitespace?nderungen, die diffs
verf?lschen.</p><p>Emacs und vim haben beide recht einfache Methoden zur
Entfernung von trailing whitespace. Emacs kennt das Kommande
<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
BufWritePre * :%s/\s\+$//e</code> wird das an Speichern
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,
<span class="command"><strong>perltidy</strong></span> zu verwenden, um einen einheitlichen
Stil zu erlangen. Es hat sich aber gezeigt, dass
<span class="command"><strong>perltidy</strong></span>s sehr eigenwilliges Verhalten, was
Zeilenumbr?che angeht, oftmals gut formatierten Code zerst?rt. F?r
den Interessierten sind hier die
<span class="command"><strong>perltidy</strong></span>-Optionen, die grob den beschriebenen
Richtlinien entsprechen:</p><pre class="programlisting">-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
-aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
-lp -vt=1 -vtc=1</pre></li><li class="listitem"><p>
<code class="varname">STDERR</code> ist tabu. Unkonditionale Debugmeldungen auch.
</p><p>
Lx-Office bietet mit dem Modul <code class="classname">LXDebug</code> einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen
Grund, nach <code class="varname">STDERR</code> zu schreiben.
</p><p>
Die <code class="classname">LXDebug</code>-Methode "<code class="function">message</code>" nimmt als ersten Paramter au?erdem eine Flagmaske, f?r
die die Meldung angezeigt wird, wobei "0" immer angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden und werden in
den meisten F?llen auch vom Repository zur?ckgewiesen.
</p></li><li class="listitem"><p>
Alle neuen Module m?ssen use strict verwenden.
</p><p>
<code class="varname">$form</code>, <code class="varname">$auth</code>, <code class="varname">$locale</code>, <code class="varname">$lxdebug</code> und
<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
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>
<code class="varname">STDERR</code> ist tabu. Unkonditionale
Debugmeldungen auch.</p><p>Lx-Office bietet mit dem Modul <code class="classname">LXDebug</code>
einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen
Grund, nach <code class="varname">STDERR</code> zu schreiben.</p><p>Die <code class="classname">LXDebug</code>-Methode
"<code class="function">message</code>" nimmt als ersten Paramter au?erdem
eine Flagmaske, f?r die die Meldung angezeigt wird, wobei "0" immer
angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden
und werden in den meisten F?llen auch vom Repository
zur?ckgewiesen.</p></li><li class="listitem"><p>Alle neuen Module m?ssen use strict verwenden.</p><p>
<code class="varname">$form</code>, <code class="varname">$auth</code>,
<code class="varname">$locale</code>, <code class="varname">$lxdebug</code> und
<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
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