Beispieldatei inklusive Docblock-Kommentaren

Der Quellcode von PEAR-Packages wird von tausenden von Menschen gelesen. Genauso kann es passieren, dass andere einmal an Ihrem Package entwicklen werden. Um es ihnen leichter zu machen, ist die Formatierung des Quellcode und der Docblöcke standarisiert. Damit können Andere Informationen einfacher finden, das sie wissen, wo sie suchen müssen.

Jeder Docblock im Beispiel enthält viele Details wie Sie die Kommentare schreiben sollten. Diese Instruktionen sind aus zwei Gründen wichtig. Erstens können Benutzer und Entwickler schneller verstehen, was Ihr Code tut. Zweitens wird auf der PEAR-Webseite die Quellcode-Dokumentation für jedes Release von jedem Package bereitgestellt und Sie sollten auch dafür sorgen, dass diese Möglichkeit sinnvoll genutzt werden kann.

Bitte achten Sie auch auf den Einsatz von vertikalen und horizontalen Leerräumen. Sie sind Bestandteil der Standards.

Die "Fold Markers" (// {{{ und // }}}) sind optional. Wenn Sie nicht benötigt werden, entfernen Sie die Einstellung foldmethod=marker aus dem Block mit Vim-Einstellungen.

<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * Kurze Beschreibung des Datei-Inhalts
 *
 * Lange Beschreibung des Datei-Inhaltes, wenn erforderlich.
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS:
<?php
$
?>
Id:$
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      File available since Release 1.2.0
 * @deprecated File deprecated in Release 2.0.0
 */

/**
 * Das ist ein "Docblock-Kommentar", auch bekannt als "docblock"/"Docblock"
 * Der Klassen-Docblock weiter unten enthält eine Beschreibung wie sie
 * geschrieben werden.
 */
require_once 'PEAR.php';

// {{{ constants

/**
 * Methoden geben diesen Wert im Erfolgsfall zurück.
 */
define('_NET_SAMPLE_OK', 1);

// }}}
// {{{ GLOBALS

/**
 * Die Anzahl der erzeugten Objekte
 * @global int $GLOBALS['NET_SAMPLE_Count']
 */
$GLOBALS['_NET_SAMPLE_Count'] = 0;

// }}}
// {{{ Net_Sample

/**
 * Ein Beispiel wird Code entsprechend der PEAR-Standards aussieht
 *
 * Anmerkung des Übersetzers: Quelltext-Kommentare sollten natürlich
 * durchgängig in Englisch erfolgen!
 *
 * Ein Docblock-Kommentar beginnt mit "/**" am Anfang.  Beachten Sie, das "/"
 * beginnt mit der normalen Einrückung und die Sterne darunter stehen in der
 * selben Textspalte wie der erste Stern. Der letzte Zeile des Kommentar-Blocks
 * sollte unmittelbar das zu dokumentierende Element folgen,
 * Vermeiden Sie zusätzliche Leerzeilen. Ergänzen Sie eine Leerzeile
 * zwischen Absätzen im Kommentartext, genauso zwischen Kommentartext und dem
 * ersten @-Tag. Ein Zeilenumbruch im Kommentartext sollte nach 80 Zeichen
 * erfolgen.
 *
 * Docblöcke können nur für eine begrenzte Anzahl an Elementen verwendet
 * werden (Klassen, Eigenschaften, Methoden, Konstanten, Include und
 * globale Variablen. In der Dokumentation zu phpDocumentor finden Sie mehr
 * Informationen dazu:
 * http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html
 *
 * Der Javadoc Style Guide ist eine exzellente Quelle wie man Kommentare
 * formulieren sollte. Letztlich sind diese Informationen eine Zusammenfassung
 * davon, andererseits gibt es aber auch einige Abweichungen davon.
 * http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide
 *
 * Diese erste Zeile jedes Docblocks ist eine Zusammenfassung. Sie sollte
 * genau einen Satz umfassen, ohne Punkt am Ende. Zusammenfassungen für
 * Klassen, Eigenschaften und Konstanten sollten nicht deren Namen enthalten
 *
 * Die unten aufgeführten Tag werden üblicherweise für Klassen benutzt.
 * Die Tags @category bis @version sind erforderlich. Die Übrigen
 * sollten ergänzt werden, wenn erforderlich. Verwenden Sie die Tags
 * in der Reihenfolge, wie hier aufgeführt. phpDocumentor bietet
 * weitere Tags, verwenden Sie diese, wenn erforderlich.
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */
class Net_Sample
{
    // {{{ properties

    /**
     * Der Zustand von foo's universe
     *
     * Potentielle Werte sind 'good', 'fair', 'poor' und 'unknown'.
     *
     * @var string
     */
    var $foo = 'unknown';

    /**
     * The status of life
     *
     * Vergessen Sie nicht, dass private Elemente mit einem
     * Unterstrich beginnen müssen.
     *
     * @var bool
     * @access private
     */
    var $_good = true;

    // }}}
    // {{{ setFoo()

    /**
     * Registriert den Zustand des Foo-Universums
     *
     * Die Zusammenfassung für eine Methode sollte besser in der 3. Person 
     * Einzahl statt in der 2. Person formuliert werden.
     * Das Verb sollte am Anfang stehen.
     *
     * Die Zusammenfassung sollte mehr Informationen liefern, die über den
     * Methodennamen hinaus gehen. Die besten Methodennamen sind
     * selbst beschreibend, sie sagen was die Methode im Grunde macht.
     * Wenn die Zusammenfassung den Methodennamen nur in Form eines
     * Satzes wiederholt, liefert sie keine zusätzlichen Informationen.
     *
     * Beispiele für die Zusammenfassung:
     *   + Sets the label              (empfohlen)
     *   + Set the label               (vermeiden)
     *   + This method sets the label  (vermeiden)
     *
     * Als nächstes werden die üblichen Tags für Methoden angeführt.
     * Ein @param-Tag muss für jeden Parameter angegeben werden.
     * Die Tags @return und @access sind wahlfrei. Das @throw-Tag
     * muss angegeben werden, wenn die Methode Exceptions wirft.
     * Das Tag @static ist erforderlich, wenn die Methode statisch
     * aufgerufen werden kann. Die übrigen Tags brauchen Sie nur
     * angeben, wenn diese benötigt werden. Bitte geben Sie die
     * Tags in der Reihenfolge an, wie sie hier aufgeführt sind.
     * phpDocumentor bietet weitere Tags, benutze Sie diese, wenn
     * es sinnvoll ist.
     *
     * Das @param-Tag umfasst den Datentypen, den Parameter-Namen, gefolgt
     * von einer Beschreibung. Per Konvention sollte die Beschreibung beginnen
     * mit dem Datentyp, dem ein Artikel ("a", "an" oder "the") vorangestellt
     * werden kann. Setzen Sie zwei Leerzeichen zwischen dem Namen
     * des Parameters und seiner Beschreibung für eine bessere Lesbarkeit.
     *
     * Wenn Sie einen Satz schreiben, starten Sie nicht mit einem
     * Großbuchstaben und beenden Sie ihn nicht mit einem Punkt:
     *   + the string to be tested
     *
     * Wenn Sie mehr als einen Satz schreiben, setzen Sie einen Punkt und
     * beginnen Sie den zweiten Satz mit einem Großbuchstaben:
     *   + the string to be tested. Must use UTF-8 encoding.
     *
     * Das @return-Tag sollte den Datentyp und eine Beschreibung des
     * zurückgegebenen Wertes enthalten. Der Datentyp kann einer von PHP's
     * Datentyp sein (int, float, bool, string, array, object, resource, mixed)
     * und sollte den primär zurückgegebenen Wert enthalten. Z.B.
     * eine Methode gibt korrekterweise ein Objekt zurück und nur im
     * Fehlerfall 'false', dann sollten Sie 'object' angeben statt
     * 'mixed'. Verwenden Sie 'void' wenn nicht zurückgegeben wird.
     *
     * Hier ein Beispiel für Quellcode-Texte:
     * <code>
     * require_once 'Net/Sample.php';
     *
     * $s = new Net_Sample();
     * if (PEAR::isError($s)) {
     *     echo $s->getMessage() . "\n";
     * }
     * </code>
     *
     * Hier ein Beispiel für Nicht-PHP-Code:
     * <samp>
     * pear install net_sample
     * </samp>
     *
     * @param string $arg1  the string to quote
     * @param int    $arg2  an integer of how many problems happened.
     *                       Rücken Sie nachfolgende Zeilen in der Beschreibung
     *                       entsprechend ein.
     *
     * @return int  the integer of the set mode used. FALSE if foo
     *               foo could not be set.
     * @throws exceptionclass  [description]
     *
     * @access public
     * @static
     * @see Net_Sample::$foo, Net_Other::someMethod()
     * @since Method available since Release 1.2.0
     * @deprecated Method deprecated in Release 2.0.0
     */
    function setFoo($arg1, $arg2 = 0)
    {
        /*
         * Das ist ein "Block Kommentar". Das Format entspricht
         * den obigen Kommentaren, mit der Ausnahme, das der Kommentarbeginn
         * nur einen Stern enthält.
         * phpDocumentor wertet diese nicht aus.
         */
        if ($arg1 == 'good' || $arg1 == 'fair') {
            $this->foo = $arg1;
            return 1;
        } elseif ($arg1 == 'poor' && $arg2 > 1) {
            $this->foo = 'poor';
            return 2;
        } else {
            return false;
        }
    }

    // }}}
}

// }}}

/*
 * Local variables:
 * tab-width: 4
 * c-basic-offset: 4
 * c-hanging-comment-ender-p: nil
 * End:
 */

?>

Best practices (Previous) Die PEAR-Werkzeugkiste (Next)
Last updated: Sun, 19 Dec 2010 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by: clbustos
This sample doesn't comply with Code Sniffer.
$ phpcs pear_sample_file.phps
--------------------------------------------------------------------------------
FOUND 3 ERROR(S) AND 1 WARNING(S) AFFECTING 3 LINE(S)
--------------------------------------------------------------------------------
72 | WARNING | Line exceeds 85 characters; contains 105 characters
148 | ERROR | There must be exactly one blank line before the tags in
| | function comment
195 | ERROR | Parameters must appear immediately after the comment
195 | ERROR | Expected 1 space after the longest variable name
--------------------------------------------------------------------------------