Top/Datei-Level-Kommentare
Jede PHP-Datei außerhalb von /template muss mit einem Copyright-Vorspann und einer Beschreibung des Inhalts der Datei eingeleitet werden:
/**
* filename - Short description for file
*
* Long description for file (if any)...
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of
* the License, or (at your option) any later version.
*
* @author name <email>
* @license http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
* @category Stud.IP
*/
Class-Kommentare
Jede Klasse muss einen Docblock haben, der den Nutzen und(!) die Verwendung beschreibt.
/**
* This class provides a singleton instance that is used to manage PDO database
* connections.
*
* Example of use:
*
* # getting a PDO connection
* $key = 'studip';
* $db = DBManager::get($key);
* $db->query('SELECT * FROM user_info');
*
* # setting a PDO connection
* $manager = DBManager::getInstance();
* $manager->setConnection('example', 'mysql:host=localhost;dbname=example',
* 'root', '');
*
**/
Wenn die Klasse schon ausführlich im Top-Level-Kommentar beschrieben wurde, darf man stattdessen dorthin verweisen: "für eine ausführliche Beschreibung siehe Kommentar am Anfang dieser Datei".
Methoden- und Funktionskommentare
Jede Funktion und Methode muss einen Docblock haben, der beschreibt, was die Funktion/Methode tut und wie man sie verwendet. Die Kommentare sollten deskriptiv ("Opens the file") und nicht imperativ ("Open the file") sein. Für gewöhnlich braucht der Kommentar nicht beschreiben, wie die Funktion funktioniert. Solche Kommentare sollten direkt im Quelltext stehen.
Die folgenden Dinge sollten im Kommentar enthalten sein:
- eine Beschreibung der Funktion
- alle Argumente und ihre Beschreibung
- alle möglichen Rückgabewerte und ihre Beschreibung
- ob und wann die Funktion Exceptions wirft
Es müssen ganze Sätze verwendet werden. Funktionen sollten ebenso wie Klassen deskriptiv (in dritter Person) kommentiert werden.
Wenn Getter/Setter-Methoden, Konstruktoren oder Destruktoren nichts unerwartetes tun, darf die Beschreibung der Funktion/Methode weggelassen werden.
/**
* Returns the value of the selected query parameter as a string.
*
* @param string $param parameter name
* @param string $default default value if parameter is not set
*
* @return string parameter value as string (if set), else NULL
*/
Property Comments
TODO
