Regel 12: Funktionen, Parameter und Rückgabewerte gut dokumentieren

Funktionen sollten immer einen Rückgabewert (Return-Parameter) haben. Falls Ihre Funktion ausschließlich zur Verarbeitung oder zur Ausgabe gedacht ist, sollte die Funktion trotzdem TRUE oder FALSE zurückliefern. Dieses ist dann ein Indikator dafür, ob die Funktion erfolgreich oder nicht erfolgreich gearbeitet hat.

Wie schon erwähnt müssen Funktionen, Parameter und Rückgabewerte sauber dokumentiert werden. Das gilt auch für die Rückgabewerte. Bezeichner und Parameter müssen "sprechend" und aussagekräftig sein.

Ungültig

   function con($h, $u, $p, $d)
   {
      // do something
   }

Funktionsname: Der Name/Bezeichner einer Funktionen sollte nach Möglichkeit ein Verb enthalten und genau beschreiben, was die Funktion macht. Ein Bezeichner sollte eher zu lang sein, als zu kurz. Aber "print_login_status_for_a_given_user()" würde zu weit gehen. Die Funktion sollte besser "print_user_login_status()" oder nur "print_login_status()" heißen.

Parameter einer Funktion: Parameter unterliegen denselben Richtlinien wie alle anderen Bezeichner. Funktionen, die alle "do($a, $b, $c)" heißen und ebenso kryptische Parameter enthalten, widersprechen dem Coding Standard. Wenn man eine Funktion nur anhand ihres Names und anhand der Parameter benutzen kann, ist das für jeden anderen Programmierer im Team eine Hilfe.

Gültig

   /**
    * This function creates a RDBMS connection (mysql_connect) and
    * selects a database (mysql_select_db). Returns TRUE or FALSE.
    * (...)
    */
   function connect_rdbms_select_database($host, $user, $password, $database)
   (...)

Selbst ohne die Beschreibung der Parameter, kann man sich bei dieser Variante schon anhand des Namens viel besser vorstellen, was die Funktion macht. Die Funktion wird TRUE zurückliefern, wenn sowohl die Verbindung zum RDBMS, als auch zur Datenbank erfolgreich ist.

Zitat aus dem Wikipedia: Extreme Programming

Ein weiterer wichtiger Punkt ist die hohe Qualität, die gemäß [Extreme Programming] im Gegensatz zu anderen Faktoren wie Ressourcen, Funktionsumfang oder Endtermin nicht diskutabel ist. Hiermit unterscheidet sich diese Grundeinstellung von vielen anderen Methoden der Softwareerstellung, bei denen Software zu einem bestimmten Zeitpunkt und in einem definierten Funktionsumfang fertiggestellt werden soll, worunter fast immer die Softwarequalität leidet. Gerade die Qualität ist allerdings sehr wichtig, um das Produkt einsatzfähig, fehlerfrei und erweiterbar zu halten. Software mit gutem Design, hoher Qualität ist mittelfristig kostengünstiger, erweiterbarer und weniger fehlerbehaftet als schnell erstellte sogenannte Frickelsoftware.

Zusammenfassung: Qualität und Klarheit des Codes sollten nicht durch Faulheit verhindert werden. Im Gegenteil, es müssen Grundsäulen des Programmierens sein. "Weg von Frickelsoftware und schlechten Strukturen!" sollte das Motto sein. Nicht nur neue Features sollten im Vordergrund eines Projektes stehen, sondern auch die Qualität von Source-Code und das Prinzip der Einfachheit.

PHP Coding Standard