Projekt

Allgemein

Profil

« Zurück | Weiter » 

Revision 06cb6b12

Von Moritz Bunkus vor fast 13 Jahren hinzugefügt

  • ID 06cb6b127be7185927c6a3b32d16295d55e162ea
  • Vorgänger 062940d9
  • Nachfolger b948bb61

HTML-Version der Dokumentation in UTF-8 encodieren

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
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<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
ü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) {
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
}</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
}</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>",
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.
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
} 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
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)) {
Blöcke schon. Beispiel:</p><pre class="programlisting">if (($form-&gt;{debug} == 1) &amp;&amp; ($form-&gt;{sum} - 100 &lt; 0)) {
...
}
......
$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
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
$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
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.
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
$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
<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
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
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
......
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
"<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>
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>
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