Regel 6: Jede Funktion muss mit Kommentaren versehen werden

Eine der wichtigsten Aufgaben der Programmierung liegt in der Dokumentation der Funktionen bzw. Methoden. Das ist in einem Team unverzichtbar, denn so können die anderen Team-Mitglieder alle Funktionen verstehen, verbessern und nutzen.

Zitat von Jörg Krause ("PHP4 - Grundlagen und Profiwissen", Seite 95)

Jedes Programm, auch das kleinste, sollte sauber kommentiert werden. Eine ordentliche Dokumentation erleichtert die Arbeit während der Entwicklung erheblich. Kommentare sind ein wesentlicher Bestandteil der Dokumentation. Stil und Inhalt sollten dem Programmierer die Übersicht in seinem Code erhalten, aber auch anderen mit dem Programm beschäftigten Personen die Lesbarkeit ermöglichen. Denken Sie daran, dass Ihre Überlegungen bei der Abstraktion eines Problems nicht immer ohne weiteres nachvollziehbar sind. Oft gibt es sehr viele Lösungen für eine Aufgabe. Warum Sie eine bestimmte Lösung gewählt haben und wie diese anzuwenden ist, wird in Kommentaren beschrieben.

Ich kann die Worte von Jörg Krause nur unterstreichen. Es lässt sich vortrefflich darüber streiten, ob die Berechnung einer Fakultät rekursiv oder iterativ zu lösen ist, aber das gehört nicht in einen Kommentar. Man sollte also nicht lang und breit erklären, warum diesen oder jenen Ansatz gewählt hat. Wenn man jedoch eine komplizierte Operation, mit wenigen Befehlszeilen macht, muss das kommentiert werden. Funktionen, Parameter und Rückgabewerte müssen sauber dokumentiert sein. Lieber einen Kommentar zu viel, als einen zu wenig.

Gültig

   /**
    * This function creates a RDBMS connection (mysql_connect) and
    * selects a database (mysql_select_db). Returns TRUE or FALSE.
    *
    * @param   string   $host: RDBMS/MySQL host, e.g. "localhost"
    * @param   string   $user: MySQL user, e.g. "mysql_user_cvb"
    * @param   string   $password: MySQL password, e.g. "topsecret"
    * @param   string   $database: MySQL database, e.g. "mysql_database_cvb"
    * @return  boolean  $connection_successfull: TRUE or FALSE
    */
   function connect_rdbms_select_database($host, $user, $password, $database)
   {
      $connect_rdbms = mysql_connect($host, $user, $password)
         or die('Could not connect to the MySQL RDBMS. Error: ' . mysql_error());
      $select_database = mysql_select_db($database)
         or die('Could not select the MySQL database. Error: ' . mysql_error());

      $connection_successfull = ($connect_rdbms and $select_database);

      return $connection_successfull; // returns TRUE or FALSE
   }

Pro Zeile die Erklärung für einen Parameter. Diese Zeile sollte nach Möglichkeit alles über den Parameter aussagen. Extreme Programming hat zum Ziel, einen möglichst hohen Qualitätsstandard zu setzen. Diese Funktion zeigt sehr gut, wie das erreicht werden kann und wie eine Funktion dokumentiert sein sollte. Wichtig sind die Datentypen ("string", "boolean"), die Namen aller Parameter ("$host", "$user", "$password", "$database"), eine Beschreibung und ein Beispiel. Die Angabe des Wertebereichs ist optionial.

Der Wertebereich bietet sich vor allem bei Integer-Parametern an, weil diese manchmal nur positiv verwendet werden, obwohl negative Werte auch denkbar sind. Dieses sollte aus einem Kommentar auf jeden Fall hervorgehen.
Beispiel: "@param integer $total_entries: total entries in table 'users' (range: 1 to 65536), e.g. '257', '5864' or other unsigned values"
Oder man gibt den den Datentypen aus MySQL an, wie TINYINT oder BIGINT. Sind negative Werte auch möglich, sollte auf jeden Fall ein Wertebereich angegeben werden und das Beispiel sollte eine negative und eine positive Zahl enthalten. Wie schon gesagt, die Zeile sollte nach Möglichkeit alles über den Parameter aussagen.

Wie die Erklärungen "@return" und "@param" schon vermuten lassen, sollte man sich auch hier an den Standard von Javadoc, Doxygen oder dem phpDocumentor halten, damit man eine komplette API-Referenz erstellen kann.

PHP Coding Standard