cvs: peardoc /de/chapters standards.xml

mj Mon Jan 21 12:30:49 2002 EDT Added files: /peardoc/de/chapters standards.xml Log: * Translation of Coding Standards (taken from phpdoc)

Index: peardoc/de/chapters/standards.xml +++ peardoc/de/chapters/standards.xml <?xml version="1.0" encoding="iso-8859-1"?> <chapter id="pear.standards"> <title>PEAR Codierstandards</title> <note> <simpara> Die PEAR Codierstandards gelten für Code, welcher zum Bestandteil von PEAR werden soll, und so entweder mit PHP, oder über den Download des PEAR Installationstools verfügbar ist. </simpara> </note> <sect1 id="pear.standards.indenting"> <title>Einrücken</title> <para> Benutzen Sie Einrückungen von 4 Zeichen, ohne Tabulatoren. Wenn Sie Emacs zum editieren von PEAR Code verwenden, sollten Sie den indent-tabs-mode auf nil setzen. Hier ist ein Beispiel für einen mode-hook, welcher Emacs entsprechend dieser Richtlinien konfiguriert (versichern Sie sich, daß der mode-hook auch aufgerufen wird, wenn Sie PHP Dateien editieren): <programlisting role="elisp"> (defun php-mode-hook () (setq tab-width 4 c-basic-offset 4 c-hanging-comment-ender-p nil indent-tabs-mode (not (and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name)) (string-match "\.php$" (buffer-file-name)))))) </programlisting> </para> <para>Hier sind die vim rules für das gleiche Problem: <programlisting role="vim"> set expandtab set shiftwidth=4 set tabstop=4 </programlisting> </para> </sect1> <sect1 id="pear.standards.control"> <title>Kontrollstrukturen</title> <para> Diese beinhalten if, for, while, switch, etc. Hier ein Beispiel für eine if Anweisung, nachdem es die komplizierteste von ihnen ist: <programlisting role="php"> if ((Bedingung1) || (Bedingung2)) { Anweisung1; } elseif ((Bedingung3) &amp;&amp; (Bedingung4)) { Anweisung2; } else { Default-Anweisung; } </programlisting> </para> <simpara> Kontrollstrukturen sollten ein Leerzeichen zwischen dem Schlüsselwort und der öffnenden Klammer haben, um sie von Funktionsaufrufen besser zu unterscheiden. </simpara> <simpara> Sie sollten immer geschweifte Klammern benutzen auch wenn sie in manchen Situationen rein technisch nur optional anzuwenden sind. Sie zu verwenden erhöht nicht nur die Lesbarkeit und vermindert daher die Wahrscheinlichkeit von logischen Fehlern, wenn neue Zeilen hinzugefügt werden. </simpara> <para> Für switch-Anweisungen: <programlisting role="php"> switch (Bedingung) { case 1: Anweisung1; break; case 2: Anweisung2; break; default: Default-Anweisung; break; } </programlisting> </para> </sect1> <sect1 id="pear.standards.funcalls"> <title>Funktionsaufrufe</title> <para> Funktionsaufrufe sollten zwischen dem Funktionsnamen, der öffnenden Klammer, und dem ersten Parameter, sowie zwischen dem letzten Parameter und der schließenden Klammer keine Leerzeichen enthalten. Die einzelnen Parameter sollten zwischen den Beistrichen und dem nächsten Parameter durch Leerzeichen getrennt werden. Hier ein Beispiel: <programlisting role="php"> $var = foo($bar, $baz, $quux); </programlisting> </para> <para> Wie oben gezeigt, sollte das zur Zuweisung des Rückgabewertes einer Funktion an eine Variable verwendete Gleichheitszeichen auf jeder Seite von einem Leerzeichen umgeben sein. Im Falle eines Blocks von Zuweisungen können mehrere Leerzeichen eingefügt werden, um die Lesbarkeit zu erhöhen: <programlisting role="php"> $short = foo($bar); $long_variable = foo($baz); </programlisting> </para> </sect1> <sect1 id="pear.standards.funcdef"> <title>Funktionsdefinitionen</title> <para> Funktionsdeklarationen folgen der "eine entsprechende Klammer" Konvention: <programlisting role="php"> function fooFunction($arg1, $arg2 = '') { if (Bedingung) { Anweisung; } return $val; } </programlisting> </para> <para> Argumente mit Default-Werten werden am Ende der Argumentenliste aufgeführt. Versuchen Sie immer einen bedeutungsvollen Wert von einer Funktion zurückzugeben, wenn ein Rückgabewert angebracht ist. Hier ein etwas längeres Beispiel: <programlisting role="php"> function connect(&amp;$dsn, $persistent = false) { if (is_array($dsn)) { $dsninfo = &amp;$dsn; } else { $dsninfo = DB::parseDSN($dsn); } if (!$dsninfo || !$dsninfo['phptype']) { return $this->raiseError(); } return true; } </programlisting> </para> </sect1> <sect1 id="pear.standards.comments"> <title>Kommentare</title> <para> Inline-Dokumentation für Klassen sollten entsprechend der PHPDoc Konvention erfolgen (ähnlich Javadoc). Mehr Information über PHPDoc finden Sie hier: <ulink url="&url.phpdoc;">&url.phpdoc;</ulink> </para> <para> Weitere Kommentare, welche nicht der Klassendokumentation dienen, werden nachdrücklich empfohlen. Eine generelle Faustregel ist: Wenn Sie auf ein Stück Code blicken und denken "Wow, ich möchte das nicht versuchen und beschreiben", dass Sie es auf jeden Fall kommentieren sollten, bevor Sie vergessen, wie es funktioniert. </para> <para> Kommentare im Stil von C (/* */) und C++ (//) sind zu verwenden, während Kommentare im Stile von perl/shell (#) zu vermeiden sind. </para> </sect1> <sect1 id="pear.standards.including"> <title>Einfügen von Code</title> <para> Verwenden Sie überall dort, wo Sie bedingungslos eine Klassendatei einfügen <function>require_once</function>. Wenn Sie eine Klassendatei bedingt einfügen wollen (z.B. Fabrikmethoden) verwenden Sie <function>include_once</function>. Beide Anweisungen stellen sicher, dass die einzufügende Datei nur einmal eingefügt wird. Sie benutzen die selbe Dateiliste, weshalb Sie sich keine Sorgen über deren gleichzeitige Benutzung machen brauchen - alle mittels <function>require_once</function> eingefügten Dateien werden mittels <function>include_once</function> nicht noch einmal eingefügt. <note> <simpara> <function>include_once</function> und <function>require_once</function> sind Statements, keine Funktionen. Sie <emphasis>benötigen</emphasis> keine Klammern um den Dateinamen, um die Datei einzufügen. </simpara> </note> </para> </sect1> <sect1 id="pear.standards.tags"> <title>PHP Code Tags</title> <para> Benutzen Sie <emphasis>immer</emphasis> <literal>&lt;?php ?></literal> um den PHP Code zu begrenzen, und nicht die Kurzform <literal>&lt;? ?></literal>. Dies ist zur PEAR Konformität erforderlich und ist auch der portabelste Weg, PHP Code auf verschiedenen Betriebssystemen bzw. Setups einzufügen. </para> </sect1> <sect1 id="pear.standards.header"> <title>Kommentare im Dateikopf</title> <para> Alle Source Code-Dateien in der PEAR Kerndistribution sollten den folgenden Kommentarblock am Anfang der Datei enthalten: <programlisting role="php"> /* vim: set expandtab tabstop=4 shiftwidth=4: */ // +----------------------------------------------------------------------+ // | PHP version 4.0 | // +----------------------------------------------------------------------+ // | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group | // +----------------------------------------------------------------------+ // | This source file is subject to version 2.0 of the PHP license, | // | that is bundled with this package in the file LICENSE, and is | // | available at through the world-wide-web at | // | http://www.php.net/license/2_02.txt. | // | If you did not receive a copy of the PHP license and are unable to | // | obtain it through the world-wide-web, please send a note to | // | license@php.net so we can mail you a copy immediately. | // +----------------------------------------------------------------------+ // | Authors: Original Author &lt;author@example.com> | // | Ihr Name &lt;you@example.com> | // +----------------------------------------------------------------------+ // // &dollar;Id&dollar; </programlisting> </para> <para> Es gibt keine festen Regeln, wann ein neuer Code Autor für seine Beiträge der Liste von Autoren hinzugefügt werden sollte. Generell sollten dessen Änderungen in die Kategorie "Erheblich" fallen (d.h. sie sollten irgendwo bei 10 bis 20 Prozent der Codeänderungen liegen). Ausnahmen könnten für das Umschreiben von Funktionen oder das Beisteuern einer neuen Logik gemacht werden. </para> <para> Einfache Reorganisation von Code oder das beheben von Bugs würde ein Hinzufügen einer neuen Person in die Liste der Autoren nicht rechtfertigen. </para> <para> Dateien außerhalb des PEAR Kernarchivs sollten einen ähnlichen Block mit Copyright, Lizenz, und den Autoren aufweisen. Alle Dateien sollten außerdem die modeline Kommentare enthalten, um die Konsistenz zu fördern. </para> </sect1> <sect1 id="pear.standards.cvstags"> <title>CVS Tags</title> <simpara> Dieses Kapitel betrifft nur Pakete, welche CVS auf cvs.php.net verwenden. </simpara> <para> Fügen Sie das &dollar;Id&dollar; CVS Schlüsselwort in jede Datei ein. Wenn Sie eine Datei editieren und dieses Schlüsselwort noch nicht vorhanden ist, fügen Sie es bitte hinzu (oder ersetzen Sie bereits vorhandene Formen wie "Last Modified:", etc.). <!-- <note> <simpara> Wir haben einen speziellen $Horde Tag in Horde CVS, um unsere Versionen getrennt zu verfolgen; wir könnten das gleiche tun und einen $PEAR Tag einführen, welcher auch bleiben würde, wenn die PEAR Dateien einmal von einem anderen Source-Kontrollsystem verwaltet werden, etc. </simpara> </note> --> </para> <para> Der Rest dieses Kapitels setzt ein Grundwissen über CVS Tags und Branches voraus. </para> <para> CVS Tags werden benutzt, um zu kennzeichnen, welche Revision der Dateien zu einem bestimmten Release gehören. Die folgende Liste beschreibt die benötigten bzw. vorgeschlagenen CVS Tags: <variablelist> <varlistentry> <term>RELEASE_<replaceable>n_n</replaceable></term> <listitem> <simpara> (benötigt) Wird verwendet, um ein Release zu kennzeichnen. Wenn Sie es nicht verwenden, können Sie später nicht mehr zurückgehen, und Ihr Paket, wie es zum Zeitpunkt dieses Releases war, vom CVS Server holen. </simpara> </listitem> </varlistentry> <varlistentry> <term>QA_<replaceable>n_n</replaceable></term> <listitem> <simpara> (branch, optional) Wenn Sie vor einem Release einen Release Candidate herausbringen möchten, empfiehlt sich die Erstellung eines Branches. So können Sie das Release isolieren, und vor dem endgültigen Release nur mehr Fixes von kritischen Fehler einspielen, während im Hauptzweig die normale Entwicklung weitergeführt wird. </simpara> </listitem> </varlistentry> <varlistentry> <term>MAINT_<replaceable>n_n</replaceable></term> <listitem> <simpara> (branch, optional) Wenn Sie "Micro-Releases" (z.B. 1.2.1, usw. nach 1.2), können Sie auch für diese einen Branch erstellen, wenn im Hauptzweig starke Aktivitäten sind, und Sie nur kleinere Änderungen zwischen den "Micro-Releases" durchführen möchten. </simpara> </listitem> </varlistentry> </variablelist> Es wird nur der RELEASE Tag benötigt, der Rest wird entsprechend Ihren Bedürfnissen empfohlen. </para> <para> Folgendes Beispiel zeigt, wie man das Release 1.2 des "Money_Fast" Paketes kennzeichnet: <informalexample> <screen><prompt>$ </prompt><command>cd pear/Money_Fast</command> <prompt>$ </prompt><command>cvs tag RELEASE_1_2</command> <computeroutput>T Fast.php T README T package.xml </computeroutput> </screen> </informalexample> Damit machen Sie es der Pear Webseite möglich, Sie durch den Rest Ihres Release Prozesses zu führen. </para> <para> Hier ein Beispiel, wie man einen QA Branch erstellt: <informalexample> <screen><prompt>$ </prompt><command>cvs tag QA_2_0_BP</command> ... <prompt>$ </prompt><command>cvs rtag -b -r QA_2_0_BP QA_2_0</command> <prompt>$ </prompt><command>cvs update -r QA_2_0</command> <prompt>$ </prompt><command>cvs tag RELEASE_2_0RC1</command> ...und dann das aktuelle Release des selben Zweigs: <prompt>$ </prompt><command>cvs tag RELEASE_2_0</command> </screen> </informalexample> Der "QA_2_0_BP" Tag ist ein "branch point" Tag, sprich der Ausgangspunkt des Tags. Es wird empfohlen, immer einen CVS branch von solchen Branch Points aus zu beginnen. </para> </sect1> <sect1 id="pear.standards.exampleurls"> <title>Beispiel URLs</title> <para> Verwenden Sie "example.com" lt. RFC 2606 für alle Beispiel URLs. </para> </sect1> <sect1 id="pear.standards.naming"> <title>Namenskonventionen</title> <sect2> <title>Funktionen und Methoden</title> <para> Funktionen und Methoden sollten unter Verwendung des "studly caps" Stils (auch bekannt als "bumpy case" oder "camel caps") benannt werden. Funktionsnamen sollten zusätzlich den Paketnamen als Präfix enthalten, um Kollisionen zwischen den Paketen zu vermeiden. Der Anfangsbuchstabe des Namens (nach dem Präfix) ist in Kleinbuchstaben, und jeder Anfangsbuchstabe eines neuen "Wortes" in Großbuchstaben. Ein paar Beispiele: <informaltable> <tgroup cols="3"> <tbody> <row> <entry><simpara>connect()</simpara></entry> <entry><simpara>getData()</simpara></entry> <entry><simpara>buildSomeWidget()</simpara></entry> <entry><simpara>XML_RPC_serializeData()</simpara></entry> </row> </tbody> </tgroup> </informaltable> </para> <para> Private Class Members (Klassenmitgieder, welche nur von innerhalb der Klasse aus, in der sie deklariert sind, benutzt werden sollen; PHP unterstützt derzeit noch keine "truly-enforceable" privaten Namensbereichen) beginnen mit einem einzelnen Unterstrich. Zum Beispiel: <informaltable> <tgroup cols="3"> <tbody> <row> <entry><simpara>_sort()</simpara></entry> <entry><simpara>_initTree()</simpara></entry> <entry><simpara>$this->_status</simpara></entry> </row> </tbody> </tgroup> </informaltable> </para> </sect2> <sect2> <title>Konstanten</title> <para> Konstanten sollten immer in Großbuchstaben benannt werden, und die Worttrennung sollte mit Unterstrichen erfolgen. Geben Sie als Präfix zum Konstantennamen den Namen der Klasse bzw. des Paketes an, in welcher die Konstante benutzt wird. Zum Beispiel beginnen alle Konstanten, welche von dem <literal>DB::</literal> - Paket benutzt werden, mit "<literal>DB_</literal>". </para> </sect2> <sect2> <title>Globale Variablen</title> <para> Wenn Sie in Ihrem Paket globale Variablen definieren müssen, sollte deren Name mit einem einzelnen Unterstrich, dem Paketnamen, und einem weiteren Unterstrich beginnen. Zum Beispiel benutzt das PEAR Paket eine globale Variable namens $_PEAR_destructor_object_list. </para> </sect2> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->