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 plus Parameter gut dokumentiert und beschrieben werden. Das gilt auch für die Rückgabewerte. Bezeichner und Parameter müssen "sprechend" und aussagekräftig definiert werden.

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

   function connect_rdbms_select_database($host, $user, $password, $database)
   {
      $connect_rdbms = mysql_connect($host, $user, $password);
      $select_database = mysql_select_db($database);
      $connection = ($connect_rdbms and $select_database);
      return $connection;
   }

In dieser Version kann man sich schon anhand der ersten Zeile 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