PHP Coding Standard - Regeln und Empfehlungen
←
→
Transkription von Seiteninhalten
Wenn Ihr Browser die Seite nicht korrekt rendert, bitte, lesen Sie den Inhalt der Seite unten
PHP Coding Standard PHP Coding Standard - Regeln und Empfehlungen Autor: Claus van Beek Vorlagen: Programming in C++ - Rules and Recommendations (written by Mats Henricson and Erik Nyquist) | PHP Coding Standard (rewritten for PHP by Fredrik Kristiansen) | phpBB Coding Guidelines Homepage: http://php-coding-standard.de Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 1 by Claus van Beek
PHP Coding Standard Table Of Contents 1. Vorwort ................................................................................................................................ 4 2. Sinn und Zweck eines Coding Standard ............................................................................. 6 3. Regel 0: Immer wenn eine Regel gebrochen wird, muss das deutlich und erkennbar dokumentiert werden ............................................................................................................... 8 4. Regel 1: Das Prinzip der Einfachheit - Struktur und Übersichtlichkeit................................. 9 5. Regel 2: Dateien, die inkludiert werden, sollten mit "*.inc.php" enden oder in einem Unterverzeichnis liegen ......................................................................................................... 11 6. Regel 3: Jede PHP-Datei muss das Copyright und einen Kommentar enthalten, der die Funktionalität beschreibt........................................................................................................ 12 7. Regel 4: Die Sprache für Kommentare und Bezeichner sollte Englisch sein .................... 14 8. Regel 5: Jede Datei wird mit Änderungskommentaren und einem Zeitstempel versehen 15 9. Regel 6: Jede Funktion muss mit Kommentaren versehen werden .................................. 16 10. Regel 7: Lange Kommentare sollten mit /* und kurze Kommentare mit // gemacht werden................................................................................................................................... 18 11. Regel 8: Alle Bezeichner werden aussagekräftig und eindeutig definiert........................ 20 12. Regel 9: Benennung von Variablen und Funktionen erfolgen mit Unterstrich und in Kleinbuchstaben .................................................................................................................... 22 13. Regel 10: Konstanten werden in Großbuchstaben defniert............................................. 23 14. Regel 11: Auf keinen Fall Abkürzungen verwenden, die zweideutig sein können .......... 24 15. Regel 12: Funktionen, Parameter und Rückgabewerte gut dokumentieren.................... 26 16. Regel 13: Die Klammern für eine Funktion () stehen direkt am Funktionsnamen ........... 28 17. Regel 14: Funktionen mit langen oder vielen Parametern müssen übersichtlich notiert werden................................................................................................................................... 29 18. Regel 15: Der Code muss vom Design getrennt werden (Template Engine).................. 30 19. Regel 16: Alle Templates müssen validiert werden......................................................... 32 20. Regel 17: Bezeichner einer Klasse werden mit Großbuchstaben voneinander getrennt 33 21. Regel 18: Keine magischen Zahlen................................................................................. 34 22. Regel 19: SQL-Befehle werden groß geschrieben.......................................................... 35 23. Regel 20: Variablen in Zählschleifen werden mit einem Buchstaben definiert................ 36 24. Regel 21: Trinitäts-Operatoren dürfen nicht verschachtelt werden ................................. 37 Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 2 by Claus van Beek
PHP Coding Standard 25. Regel 22: INSERT-Anweisungen müssen die einzelnen Spalten für die VALUES-Klausel enthalten................................................................................................................................ 38 26. Regel 23: Code, der nicht benutzt wird, muss gelöscht werden...................................... 39 27. Empfehlung 1: Geschweifte Klammern werden im Allman-Stil eingerückt...................... 40 28. Empfehlung 2: Jede Kontrollstruktur hat einen Block mit Klammern............................... 42 29. Empfehlung 3: Zum Einrücken von Quellcode werden Tabulatoren verwendet.............. 44 30. Empfehlung 4: Die Benutzung von Zahlen in Bezeichnern ist zu vermeiden .................. 46 31. Empfehlung 5: Es sollte Subversion und ein Bugtracker-System benutzt werden.......... 47 32. Empfehlung 6: Keine Anführungsstriche bei String-Deklarationen.................................. 48 33. Empfehlung 7: Debug-Informationen von Anfang an einbinden...................................... 49 34. Empfehlung 8: Werte für FOR-Schleifen richtig setzen................................................... 50 35. Richtig und Falsch 1: Klammern setzen und Abkürzungen............................................. 51 Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 3 by Claus van Beek
PHP Coding Standard 1. Vorwort Bevor ich hier auf die verschiedenen Vorteile des PHP Coding Standards eingehe, möchte ich den Autoren des Originals (für C++): • Mats Henricson • Erik Nyquist und dem Übersetzer "Joseph Supanich" danken. Ohne diese drei Personen wäre dieser Coding Standard nicht möglich gewesen. Außerdem habe ich mich von Paul Waring und Fredrik Kristiansen inspirieren lassen. Anstatt Name wird im Coding Standard oft das Wort "Bezeichner" verwendet. Gültige Programmierbeispiele werden farblich von ungültigen abgehoben. So ist leichter zu erkennen, wo der PHP Coding Standard eingehalten wird und wo nicht. Wenn im Text das Wort "Variable" steht und es um den Bezeichner bzw. die Definition eines (Variablen)Namens geht, so kann an die Stelle auch "Funktion", "Konstante" etc. stehen. Die Namenskonvention für Bezeichner sind global gültig. Ausnahmen, zum Beispiel für Namenskonventionen bei Klassen, werden explizit aufgeführt und erklärt. Es gibt jetzt schon einige Coding Standards für PHP. Die Auswahl sollte einem Programmier-Team nicht schwer fallen, aber sorgfältig gemacht werden, denn ein Coding Standard hat keinen Sinn, wenn er nicht von allen Programmierern eingehalten wird. Sinn und Zweck dieses Dokuments ist nicht, einen einzigen gültigen PHP Coding Standard zu entwerfen. Es wird in jedem Team bestimmte Anforderungen und Vorlieben geben. Das ist ok. Es ist nicht ok, wenn jeder Programmierer seinen Vorlieben nachgibt und eine Variable, mal so und mal anders benennt. Dieses muss durch Kontrollen und Teamwork, am besten durch Extreme Programming, sichergestellt werden. "Extreme Programming" wird hier genannt, weil es das "Pair Programming" vorschlägt, das automatisch ein 4-Augen-Prinzip enthält. Wenn man sich für einen Coding Standard entschieden hat, sollten alle Änderungen, die man vornimmt, schriftlich niedergelegt werden. Jede Regel, die vom Team abgelehnt wird, sollte abgeändert oder gelöscht werden. Jedoch muss beides dokumentiert werden, schon damit sich jeder an die Änderung halten kann. Auch neue Mitglieder im Team werden sich dann leichter zurechtfinden und keine Regeln befolgen, die veraltet sind. Wenn Sie es vorziehen allein zu arbeiten, brauchen Sie keinen Coding Standard. Sie brauchen auch keine Kommentare oder sprechende Variablen. Aber wenn Sie planen, Ihr Projekt zu veröffentlichen (zum Beispiel bei sourceforge.net), dann sollten Sie es von Anfang an richtig machen. Gerade in der PHP-Welt ist die Wahrscheinlichkeit groß, dass Sie bei einem GPL-Projekt Hilfe bekommen. Früher oder später werden sich diese Helfer Ihren PHP-Code ansehen und das Ergebnis sollte sich doch sehen lassen können, oder? Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 4 by Claus van Beek
PHP Coding Standard Zu meiner Person: Ich, Claus van Beek, bin in fünf große Projekte involviert gewesen oder ich bin es noch. Bis auf eine Ausnahme, haben alle Projekte ohne Coding Standard angefangen und es wurden nahezu keine Tests durchgeführt. Konzepte wie Extreme Programming und/oder Refactoring wurden nie beachtet, obwohl diese Konzepte älter als PHP4 und PHP5 sind. Beim XMB wurde zu Testzwecken das Feld "dummy" in die Datenbank eingefügt. Die Spalte blieb jedoch in allen RCs und der endgültigen Version erhalten. Nur deswegen musste zusätzliche Arbeit in das "ugrade.php" gesteckt werden. In Papoo (Version 3.0) gibt es redundante und viele leere Felder in der Datenbank. Feststehende Begriffe wie "LAN" (Local Area Network) werden als Abkürzung für "language" verwendet. Schnittstellen von Methoden werden so gut wie nie dokumentiert. Die gewachsenen Strukturen wuchern immer mehr aus. Oft höre ich auch Aussagen wie "Das ist nur ein Test-Skript" das bedeutet dann ungefähr: "Ich mache die Doku und die Kommentare später", aber viel zu oft passiert das nicht. Zitat eines unbekannten Programmierers Man hat anscheinend immer die Zeit alles zweimal zu machen, aber es fehlt immer die Zeit, es von Anfang an richtig zu machen. Ich dachte, ich hätte dieses Zitat irgendwo gelesen, aber Google findet dieses Zitat nicht. Da ich in meinen Projekten den Azubis immer wieder predige: "Erst Strukturen, dann Coden, dann Tests", musste ich dieses Zitat jedoch verwenden. Das Extreme Programming geht davon aus, dass erst die Modultests und dann der Code geschrieben wird. Ich stehe diesem Ansatz kritisch gegenüber, weil das schreiben von Tests manchmal ähnlich aufwendig ist, wie die Programmierung selbst. Die meisten Firmen und Programmierer arbeiten aber mit nur ganz wenigen Strukturen und verzichten auf automatisierte Tests. Ohne Refactoring, ohne (Modul)Tests und ohne PHP Coding Standard sind wachsende, ausufernde Strukturen und unverständlicher Programmcode unvermeidbar. Irgendwann kann das Projekt niemand mehr kontrollieren und die Fehlersuche wird enorm erschwert. Um das zu verhindern, müssen alle PHP-Projekte einen • Coding Standard • Refactoring • Modul- und andere Tests einsetzen, um die Qualität der Software sicher zu stellen. Andere Verfahren wie Bug-Tracker-Systeme (wie Mantis) haben sich ebenfalls etabliert. Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 5 by Claus van Beek
PHP Coding Standard
2. Sinn und Zweck eines Coding Standard
Wenn man dem Extreme Programming folgt, wird man wissen, dass die Einhaltung eines Coding
Standards ein wichtiger Bestandteil der gesamten Projektarbeit ist. Darüber hinaus gibt es jedoch
auch andere wichtige Faktoren:
• Kommunikation
• Urlaubsvertretung
• funktionierender Code
• übersichtlicher Code
• Module und Modultests
• Wiederverwendbarkeit des Codes
• einfache Wartung des Codes
• Code, der leicht zu erweitern ist
• Unterstützung von Refactoring
um nur einige zu nennen. Bis auf den Punkt "Kommunikation" unterstützt ein Coding Standard alle
genannten Punkte. Selbst die Urlaubsvertretung wird einfacher, denn wenn jeder den Code des
anderen versteht, kann man auch schnell Bug-Fixes vornehmen oder Module des anderen
verwenden ohne das Rad neu zu erfinden.
Zitat von Martin Fowler ("Refactoring - Improving the design of existing code", Seite 15)
Any fool can write code that a computer can understand. Good programmers write code that
humans can understand.
Um diese Ziele zu erreichen, muss eine PHP-Applikation
• leicht zu lesen
• leicht verständlich
• gut dokumentiert
• durch verschiedene Programmierer wartbar
• frei von typischen Fehlern
sein. Im besten Falle kann sogar ein Kunde die Module der PHP-Applikation verstehen und weiter
verwenden. Wenn man das nicht möchte, so ist die logische Schlussfolgerung nicht Kommentare und
Struktur wegzulassen, sondern den PHP-Code zu verschlüsseln, zum Beispiel mit dem Zend Guard
oder dem PHP Encoder.
Das Ziel von leicht verständlichem Source-Code ist erreicht, wenn jedes Mitglied des Teams, jedes
Modul aus dem Stehgreif erklären kann. Nicht zuletzt soll jede Arbeit am Projekt, dem Code und der
Dokumentation Spaß machen. Je höher der Frustfaktor ist, je unübersichtlicher Strukturen und Code
sind, desto höher ist die Wahrscheinlichkeit, das die Arbeit keinen Spaß mehr macht. Das gilt es auf
jeden Fall zu verhindern.
Es folgen die Regeln, die einzuhalten und nicht gebrochen werden sollten. Im Gegensatz dazu
stehen die Empfehlungen, denen man nicht folgen muss. Als letztes kommt "Richtung und Falsch".
Die Beispiele hier sollen die Regeln und Empfehlungen verdeutlichen.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 6
by Claus van BeekPHP Coding Standard Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 7 by Claus van Beek
PHP Coding Standard
3. Regel 0: Immer wenn eine Regel gebrochen wird, muss das deutlich und erkennbar
dokumentiert werden
Dies ist die wichtigste Regel, denn sie erlaubt zum einen Freiheit und erfordert zum anderen genaue
Dokumentation, warum man sich für einen Bruch der Regeln entschieden hat. Auch beim Brechen
von Regeln sollte das Prinzip der Einfachheit weiter angewendet werden. Beispiel: Sie wollen zwei
Variablen miteinander vergleichen und das Ergebnis "$boolean" zuweisen. Die erste Variante ist die
einfachste, aber es gibt mehrere Möglichkeiten das zu programmieren:
Gültig
// gültiger PHP Coding Standard
$boolean = (15 > 9);
Gültig
// gültiger PHP Coding Standard
if (15 > 9)
{
$boolean = TRUE;
}
else
{
$boolean = FALSE;
}
Ungültig
// ungültiger PHP Coding Standard
if (15 > 9)
$boolean = TRUE;
else
$boolean = FALSE;
Gültig
// gültiger PHP Coding Standard
$boolean = (15 > 9) ? TRUE : FALSE;
Das Beispiel zeigt kurze und ausführliche Programmierung. In jedem Fall wird mit
"var_dump($boolean);" der Wert "bool(true)" ausgegeben. Das dritte Beispiel ist nach dem PHP
Coding Standard ungültig, weil die geschweiften Klammern fehlen. Würde das Fehlen und der Grund
genau dokumentiert werden, hätte man Regel 0 beachtet. In dem hier dargestellten Fall sollte man
nach dem Prinzip der Einfachheit die erste Variante wählen.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 8
by Claus van BeekPHP Coding Standard
4. Regel 1: Das Prinzip der Einfachheit - Struktur und Übersichtlichkeit
Das Prinzip der Einfachheit besagt: "Mache alles so einfach wie möglich!" Wenn man also eine lange
und komplizierte Funktion durch eine Klasse mit vier oder fünf übersichtlichen Methoden ersetzen
kann, so ist der Aufwand nahezu immer gerechtfertigt. Kann man komplexe und unstrukturierte
iterative Programmierung durch eine elegante Rekursion ersetzen, sollte man diese Arbeit nicht
scheuen. Diese Arbeit gehört zum Programmieren, sie ist ein Teil des Refactoring.
Zitat von Steve Krug ("Don't make me think! Web Usability", Seite 11)
Die Leute fragen mich oft:
"Wenn ich ich sichergehen will, dass meine Webseite einfach zu benutzen ist, was ist das
Wichtigste, das ich beachten muss?"
Die Antwort ist einfach. Sie lautet nicht: "Alles Wichtige darf nicht mehr als zwei Klicks entfernt
sein" oder "Sprich die Sprache der User" oder auch "Sei konsistent". Sie lautet ...
"Don't make me think!"
Seit Jahren erzähle ich Leuten, dass dies mein Erstes Gesetz zur Usability ist. Und je mehr
Webseiten ich mir anschaue, desto überzeugter bin ich davon.
Steve Krug navigiert mit dem Auto lieber durch Los Angeles als durch Boston, weil die
Straßenschilder deutlich zu sehen und die Straßennamen in großen Buchstaben geschrieben sind. Er
widmet ein Kapitel der Navigation im Baumarkt und vergleicht sie mit der Navigation im Web. Was
mögen die Menschen lieber ... einen gut sortierten Supermarkt mit großen Schildern ("Süßigkeiten",
"Backwaren", "Obst und Gemüse", etc.) oder einen unübersichtlichen Supermarkt ohne Schilder?
Das Prinzip der Einfachheit findet man überall im Leben, aber in der Programmierung wird es nur
selten angewendet. Hier ist oft das Hauptprinzip: "Hauptsache es läuft!". Es sollte jedoch das Prinzip
der Einfachheit sein. Code sollte modular, wartbar und wiederverwendbar sein.
Zitat von Jörg Krause ("PHP5 - Grundlagen und Profiwissen", Seite 349)
Code-Konventionen sind (aus Sicht des PHP-Parsers) unverbindliche Vorschriften oder
Empfehlungen zur Schreibweise von Variablen und Funktionen. (...) Neben den vielen
Vorschriften, die eine Programmier- oder Skript-Sprache ausmachen, gibt es auch eine Reihe von
Empfehlungen, die Programmierern helfen, gut lesbare und saubere Programme zu schreiben.
Die Code-Konventionen sind solche Empfehlungen. Dabei geht es auch um die Pflege der
Programme durch andere Programmierer oder später durch Sie selbst. Oft entstehen Programme
unter großem Zeitdruck, die nötige Kommentierung und Dokumentation wird nur mangelhaft
möglich sein. Die für jede Sprache geltenden Konventionen erleichtern dann das Einarbeiten in
fremden oder eigenen Code.
Zum Prinzip der Einfachheit gehören automatisch Struktur und Übersichtlichkeit. Der PHP Coding
Standard wird hier verschiedene Mechanismen erklären, um das zu erreichen. Der weltweit
wichtigste und weitverbreiteste Standard ist das Einrücken von Code. Es gibt viele unterschiedliche
Meinungen zu "Tabs vs. Spaces" (Tabulatoren oder Leerzeichen), sowie die Frage "2, 4 oder 8
Leerzeichen?" beim Einrücken. Hier muss sich das Team einigen.
Die vielen Beispiele in diesem Dokument werden das Einrücken von Code besser erklären, als jede
abstrakte Formel.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 9
by Claus van BeekPHP Coding Standard Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 10 by Claus van Beek
PHP Coding Standard
5. Regel 2: Dateien, die inkludiert werden sollten, mit "*.inc.php" enden oder in einem
Unterverzeichnis liegen
Es ist besser ein Unterverzeichnis ("include" oder "inc") für die Dateien anzulegen, die per include()
oder ähnlichen Befehlen inkludiert werden. Oft werden hier Verzeichnisse wie "lib" oder "class"
verwendet. Das widerspricht jedoch dem Prinzip der Einfachheit, weil der Name "include" für jeden
PHP-Programmierer eine eindeutige Verbindung zum gleichnamigen PHP-Befehl herstellt. Das
INCLUDE-Verzeichnis kann auch für CSS- und JavaScript-Dateien verwendet werden. Empfohlen
wird jedoch ein eigenes Unterverzeichnis (zum Beispiel: "css_javascript").
Möchte man, aus welchen Gründen auch immer, alle INCLUDE-Dateien im Hauptpfad ablegen, so
muss die Dateiendung "*.inc.php" verwendet werden. "*.inc" reicht nicht aus, weil diese Dateiendung
standardmäßig nicht geparst wird und demnach alle Informationen der Datei (auch Passwörter) im
Klartext vorliegen.
Ausnahme zu Regel 2: Wenn das Team sich für eine Struktur entscheidet, die jedem Mitglied intuitiv
und einfach erscheint, sollte diese Struktur verwendet werden.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 11
by Claus van BeekPHP Coding Standard
6. Regel 3: Jede PHP-Datei muss das Copyright und einen Kommentar enthalten, der die
Funktionalität beschreibt
Der C++ Coding Standard geht davon aus, dass in jeder Datei mit Source Code auch der Dateiname
erwähnt wird. Dieses Konzept erscheint mir unlogisch, weil der Dateiname beim Bearbeiten und
Drucken bekannt sein sollte. Trotzdem steht es jedem Entwickler frei, den Dateinamen mit in den
Kopf einer Datei aufzunehmen.
Gültig
// +----------------------------------------------------------------------+
// | Copyright (c) 2002-2006 Claus van Beek |
// +----------------------------------------------------------------------+
// | This describes the following script. Basic information is provided. |
// | "LAN" = Local Area Network. Other Abbrivations are not used in this |
// | script. |
// +----------------------------------------------------------------------+
// | This library is free software; you can redistribute it and/or |
// | modify it under the terms of the GNU Lesser General Public |
// | License as published by the Free Software Foundation; either |
// | version 2.1 of the License, or (at your option) any later version. |
// +----------------------------------------------------------------------+
Das Copyright sollte zur Wahrung der eigenen Rechte oder der gewählten Lizenz in jeder PHP-Datei
erwähnt werden. Wurde das Produkt über mehrere Jahre entwickelt, dann sollte jedes Jahr erwähnt
werden.
Wenn viele Autoren an einem Projekt arbeiten und auch noch verschiedene Lizenzen im Spiel sind
(wie bei PEAR) ist es unter Umständen sinnvoll, folgende Version zu verwenden:
Gültig
/**
* Crypt_Blowfish allows for encryption and decryption on the fly using
* the Blowfish algorithm. Crypt_Blowfish does not require the mcrypt
* PHP extension, it uses only PHP.
* Crypt_Blowfish support encryption/decryption with or without a secret key.
*
*
* 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 Encryption
* @package Crypt_Blowfish
* @author Matthew Fonda
* @copyright 2005 Matthew Fonda
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version CVS: $Id: Blowfish.php,v 1.81 2005/05/30 18:40:36 mfonda Exp $
* @link http://pear.php.net/package/Crypt_Blowfish
*/
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 12
by Claus van BeekPHP Coding Standard Diesen Eintrag kann man mit Tools wie Javadoc, Doxygen oder phpDocumentor auswerten. Da sich die meisten Menschen zuerst mit einer Dokumentation auseinandersetzen, bevor sie den Source-Code durcharbeiten, ist eine API-Referenz oft hilfreich. Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 13 by Claus van Beek
PHP Coding Standard
7. Regel 4: Die Sprache für Kommentare und Bezeichner sollte Englisch sein
Bezeichner von Variablen, Funktionen, Klassen und so weiter sollten in Englisch definiert werden.
Alle Kommentare und Dokumentation sollte ebenfalls in Englisch erfolgen.
Es ist absolut notwendig und unumgänglich Source-Code zu dokumentieren. Wenn keine
zwingenden Gründe dagegen sprechen, sollten als Projektsprache Englisch genommen werden, um
Personen aus anderen Ländern einen möglichst einfachen Zugang zum Projekt zu gewähren.
Unbedingt zu vermeiden ist eine Mischung der englischen und der deutschen Sprache, gerade wenn
es um die Benennung von Variablen geht. Siehe dazu auch mehr bei den Regeln zur Benennung von
Variablen.
Ein Team entscheidet sich dazu, Deutsch als Projektsprache zu nehmen. Damit entsteht nahezu
automatisch das Problem der Sprachmischungen:
Ungültig
$select_maximum = 'SELECT MAX(id) FROM tabelle';
$result_maximum = mysql_query($select_maximum);
$eine_ganz_andere_variable = TRUE;
Wie man unschwer sehen kann, muss man in einer deutschen Sprachumgebung auf Variablen wie
• $result
• $select
• $query
• $row
verzichten und sich geeignete Äquivalente ausdenken. Auf Englisch als Projektsprache sollte nur
verzichtet werden, wenn die Englischkenntnisse des Teams "im negativen Bereich" liegen oder der
Fehlerquotient einen zweistelligen Wert hat.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 14
by Claus van BeekPHP Coding Standard
8. Regel 5: Jede Datei wird mit Änderungskommentaren und einem Zeitstempel versehen
Wenn kein SVN oder CVS zur Verfügung steht, sollte das Team eine Konvention vereinbaren, wie es
Änderungen am Source-Code dokumentiert. Zum Beispiel könnte man die Initialen jedes
Teammitglieds verwenden plus das Datum nach dem ISO 8601 Standard.
PHP
// CVB 2006-05-23: Refactoring
while ($row = mysql_fetch_assoc($result))
(...)
HTML
(...)
Es wird empfohlen fünf dieser Kommentare aufzubewahren, damit die letzten (Arbeits)Schritte
nachvollzogen werden können. Ob die Kommentare im Kopf der Datei gemacht werden oder an der
Stelle, wo die Änderungen gemacht werden, sollte das Team vor dem Projekt entscheiden und dann
einheitlich für alle Dateien umsetzen.
Ausnahme zu Regel 5: Es steht ein SVN oder CVS zur Verfügung. In diesem Fall sollte Gebrauch
von den Funktionen dieser Software gemacht werden.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 15
by Claus van BeekPHP Coding Standard
9. 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. Hier lässt sich vortrefflich darüber streiten, ob
es einen Unterschied macht, wenn die Berechnung einer Fakultät rekursiv oder iterativ gelöst wurde.
Man sollte 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.
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_user18"
* @param string $password: MySQL password, e.g. "topsecret"
* @param string $database: MySQL database, e.g. "mysql_database18"
* @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.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 16
by Claus van BeekPHP Coding Standard 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' and 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. Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 17 by Claus van Beek
PHP Coding Standard
10. Regel 7: Lange Kommentare sollten mit /* und kurze Kommentare mit // gemacht werden
Das PEAR-Projekt dokumentiert sehr ausführlich auch einzelne Variablen:
Gültig
/**
* Should data manipulation queries be committed automatically?
* @var bool
* @access private
*/
var $autocommit = true;
Man kann sich sehr leicht vorstellen, dass eine solche Verfahrensweise sehr viel Arbeit macht und es
für jede Zeile auch übertrieben wäre. Systemkritische Variablen und Konstanten sollten aber auf
diese Art und Weise dokumentiert werden.
Gültig
$boolean = ($i > $j); // IF $i > $j: $boolean becomes TRUE or FALSE
Denken Sie bei Kommentaren an die lesende Zielgruppe, aber ein wenig Fachwissen kann ruhig
vorausgesetzt werden. Wenn also die Zeile
$boolean = ($i > $j);
in Ihrem Team jeder versteht, lassen Sie den Kommentar weg.
Der C++ Coding Standard spricht von strategischen oder taktischen Kommentaren. Ein
strategischer Kommentar beschreibt eine Funktion oder einen ganzen Absatz des Source-Codes. Ein
strategischer Kommentar wird vor dem Code plaziert.
Ein taktischer Kommentar beschreibt eine bestimmte Zeile und wird - wenn möglich - ans Ende der
Zeile (also hinter dem Code) plaziert. Auch wenn der Kommentar ohne den Code nicht sinnvoll ist,
sollte man einen taktischen Kommentar verwenden.
Die Meinungen über die Art, die Menge und andere Faktoren der Dokumentation gehen stark
auseinander. Die einen finden zu viele taktischen Kommentare unübersichtlich, die anderen denken,
dass zwanzig Zeilen strategischer Kommentar für fünf Zeilen komplexen Source-Code gerade so
ausreichend ist. Jedes Team muss also eine Entscheidung darüber fällen, in welchem Maße
Kommentare angewendet werden.
Das Prinzip der Einfachheit sollte immer Anwendung finden. Das erklärte Ziel jeder Dokumentation
und jedes Kommentars muss Transparenz und Verständnis für den Source-Code sein.
Zitat aus dem Film Philadelphia: "Bitte erklären sie mir das so, als ob ich sechs Jahre alt wäre!"
Natürlich ist es unmöglich, dass ein 6-jähriger den komplexen Source-Code eines großen Projektes
versteht, aber ich kann nicht oft genug betonen, dass Teamwork, Kommunikation, Verständnis und
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 18
by Claus van BeekPHP Coding Standard Qualität des Source-Codes im Vordergrund jedes Projektes stehen müssen. Das Ziel von leicht verständlichem Source-Code ist erst erreicht, wenn jedes Mitglied des Teams, jedes Modul aus dem Stehgreif erklären kann. Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 19 by Claus van Beek
PHP Coding Standard
11. Regel 8: Alle Bezeichner werden aussagekräftig und eindeutig definiert
In einem Programm können viele Bezeichner/Namen definiert werden. Jede Variable (Funktion,
Konstante, etc.) braucht einen Bezeichner. Diese Bezeichner müssen aussagekräftig und eindeutig
definiert werden. Sie sollten nicht zu lang sein, aber auch nicht so kurz, dass die Bedeutung der
Variable unklar ist.
In jedem (guten) Programmierkurs lernen Sie sprechende Variablen zu verwenden. Sprechende
Variablen sagen etwas über den Inhalt und die Verwendung aus. Bezeichner aussagekräftig zu
definieren ist dafür eine globale Umschreibung.
Zitat aus "Einführung in Perl" von Randal L. Schwartz, Tom Phoenix und brian d foy, Seite 30
In der Regel sollten Sie Variablennamen so wählen, dass sie etwas über den Zweck der Variablen
aussagen. $r ist wahrscheinlich nicht so aussagekräftig wie $zeilen_laenge. (...) Ebenso können
richtig platzierte Unterstriche das Lesen und Verstehen eines Variablennamens erleichtern,
besonders dann, wenn der Programmierer, der Ihre Programme pflegen soll, einen anderen
sprachlichen Hintergrund hat als Sie.
Beispiel: Sie programmieren Auswertungen (englisch: reports) über den Zugriff auf einen
Bankautomat. Dazu benutzen Sie in Ihrer Funktion die PHP-Funktionen mysql_query und
mysql_num_rows. Sie könnten die Funktion "rep_mq_mnr()" nennen. Das steht für
"report_mysql_query_mysql_num_rows". Ein sehr schlechter Name für die Funktion.
1. Keine Abkürzungen verwenden, die niemand kennt.
2. Beide Versionen des Namens sagen nichts über die Funktionalität, den Sinn und Zweck und die
Arbeitsweise der Funktion aus.
Erzeugt die Funktion Grafiken? Dann wäre der Name "create_graphics()" sinnvoll. Oder das Ergebnis
von "mysql_num_rows()" enthält alle Bankautomat-Logins des heutigen Tages, dann wäre
"check_all_logins_for_today()" oder auch "get_logins_today()" eine gültige Bezeichnung. Die zweite
Variante könnte schon wieder unklar sein, denn die Übersetzung könnte auch lauten: "Hole dir heute
die Logins."
Einen Namen eindeutig zu vergeben bedeutet zum Beispiel:
• Zwei Funktionen nicht nur durch Groß- und Kleinschreibung zu unterscheiden, also nicht
Funktion A "get_data()" und Funktion B "Get_data()".
• Variablen nicht durchnummerieren, also nicht "$var1", "$var2", etc.
• Zahlen in Namen vermeiden, also eine Konstante nicht in einem Skript mit "I0" (I + Ziffer "0") und
dann im nächsten mit "IO" (I + Buchstabe "O") definieren.
Ob man die Abkürzung "IO" für "Input/Output" als bekannt voraussetzen kann, muss im Zweifelsfall
das Team entscheiden - zu Abkürzungen später mehr.
Erneut kann ich einen Fall aus der Praxis erzählen. Ein Kollege von mir definierte die Funktion "a()".
Diese Funktion gab mit echo die Zeichen "\n" aus. Warum? Er war zu faul das immer wieder zu
tippen. Wie aussagekräftig ist der Name "a()" wohl für einen anderen Programmierer?
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 20
by Claus van BeekPHP Coding Standard Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 21 by Claus van Beek
PHP Coding Standard
12. Regel 9: Benennung von Variablen und Funktionen erfolgen mit Unterstrich und in
Kleinbuchstaben
Wie schon erwähnt ist der Einsatz von Abkürzungen mit Vorsicht zu genießen. Es kann begründete
Fälle geben, wo es sinnvoll ist, eine Abkürzung zu verwenden, aber die Regel "Benennung von
Variablen und Funktionen erfolgen mit Unterstrich und in Kleinbuchstaben" soll den Einsatz von
Abkürzungen zusätzlich erschweren. Das ist Absicht, denn Abkürzungen können einem
Programmier-Team das Leben schwer machen - dazu später mehr.
Zitat aus "Einführung in Perl" von Randal L. Schwartz, Tom Phoenix und brian d foy, Seite 30
Ebenso können richtig platzierte Unterstriche das Lesen und Verstehen eines Variablennamens
erleichtern, besonders dann, wenn der Programmierer, der Ihre Programme pflegen soll, einen
anderen sprachlichen Hintergrund hat als Sie. So ist beispielsweise der Name $flachbett_scanner
besser geeignet als $flachbettscanner, da sich Letzteres auch durchaus als $flach_bettscanner
deuten lassen könnte. Bedeutet $stopid nun $sto_pid (»store process ID«, also Prozess-ID
speichern), oder $stop_id (die ID für irgendetwas, das gestoppt werden soll), oder handelt es sich
bloß um einen stupiden Rechtschreibfehler?
Um den Einsatz von Abkürzungen trotzdem zu ermöglichen und Variablen eindeutig und mit
mehreren Worten benennen zu können, benutzt man den Unterstrich zur Trennung der Wörter:
Gültig
$surname_given_name = 'van Beek, Claus';
$connect_rdbms = mysql_connect();
Kleinbuchstaben erleichtern die Suche nach Variablen. Einige Editoren und die meisten
Linux-Systeme unterscheiden zwischen Groß- und Kleinschreibung. Sie arbeiten case-sensitive. Ein
grep "*skript_name*" ein_skript.php
führt dann auf jeder Plattform zum Erfolg (wenn es eine entsprechende Variable gibt). Heißt die
Variable "$Skript_Name", wird der oben genannte Befehl fehlschlagen.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 22
by Claus van BeekPHP Coding Standard
13. Regel 10: Konstanten werden in Großbuchstaben defniert
Für Konstanten gelten die gleichen Regeln wie für andere Bezeichner. Eine Ausnahme gibt es
jedoch: Alle Konstanten werden groß geschrieben, so wie es bei php.net (Konstanten) auch
vorgeschlagen wird. Gute Bezeichner für Konstanten sind:
• START_VALUE
• DATABASE_PREFIX
• ENCRYPTION
und so weiter.
Gültig
// constants for database connection
define('HOST', 'localhost');
define('USER', 'root');
define('PASSWORD', 'your_password');
define('DATABASE', 'your_database_name');
Das Beispiel zeigt den richtigen Gebrauch Konstanten. Viele Konfigurationsdateien verwenden
Variablen. Allerdings ändert sich die Konfiguration für ein RDBMS nicht im laufenden Betrieb, also
sollten auch keine Variablen verwendet werden. Konstanten sind hier die bessere Wahl.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 23
by Claus van BeekPHP Coding Standard
14. Regel 11: Auf keinen Fall Abkürzungen verwenden, die zweideutig sein können
Stellen Sie sich vor, Sie finden in einem PHP-Skript die Variable "$back". Man könnte jetzt
annehmen, dass diese Variable etwas mit "Zurück" zu tun hat. Mir ist allerdings ein Fall bekannt, wo
"back" eine Abkürzung für "Backend" war. Im gleichen Projekt wurde auch die Abkürzung "lan" für
"language" verwendet. "LAN" ist jedoch (weltweit) eine Abkürzung für "Local Area Network".
Wenn auch nur ein Mitglied im Team über so etwas "stolpert", geht wertvolle Zeit verloren. Das muss
unter allen Umständen vermieden werden. Das man "back" schneller getippt hat als "backend" ist
natürlich wahr, aber aus solcher Faulheit - und wir reden hier von vielleicht zwei Sekunden
Mehraufwand - können sich fatale Folgen ergeben:
• Ein Team-Mitglied versucht mehrere Stunden herauszubekommen, warum in den Tabellen, die
mit "lan" beginnen, keine Spalten vorhanden sind, die Informationen über Netzwerke (LAN) oder
IP-Adressen enthalten.
• Eine Person denkt darüber nach ein AddOn oder Plugin für eine GPL-Software zu schreiben.
Aufgrund der schlechten Strukturen in der Datenbank und im Source-Code entscheidet er sich
jedoch dagegen und macht sich auf die Suche nach einem anderen, vergleichbaren
GPL-Produkt.
• In einer Besprechung wird ein Bug in der Software entdeckt. Aufgrund von fehlender
Dokumentation und vielen Abkürzungen, die selbst von den Programmierern nicht mehr
entschlüsselt werden können, wird die Suche nach dem Bug deutlich erschwert.
Diese Fälle sind nicht konstruiert, sondern meine Erfahrungen oder die Berichte von Freunden. Um
solche Probleme zu umgehen:
• verwenden Sie so wenig Abkürzungen wie möglich
• nur Abkürzungen benutzen, die jeder im Team kennt
• auf keinen Fall Abkürzungen verwenden, die zweideutig sein können
Abkürzungen vermeiden
$group_id = 1; // instead of $grpid
$name_length = 20; // instead of $namLn
$reset_printer = TRUE; // instead of $rstprt
Obwohl "group_id" nahezu genauso schnell getippt ist, wie "grpid" werden in vielen PHP-Projekten
solche kryptischen Abkürzungen benutzt. Es wäre auch möglich, die Variable "grpid" als "grPID" zu
interpretieren. "PID" ist unter Linux/Unix eine bekannte Abkürzung für "Process ID". In genau diesem
Fall würde unweigerlich das Rätsel um die Abkürzung "gr" beginnen.
Mehrere Bedeutungen sind möglich
$tp = termProcess(); // Terminate process or terminal process?
$stupid = $rst; // Typo? "$stupid" or "$stop_id"?; $rst == $result or $reset?
$success = proc(); // "proc()" == processing or procedure?
Abkürzungen wie "RDBMS" können schnell über Google gefunden werden und sind den meisten
Personen in der EDV bekannt. Sie können deswegen mit Vorsicht eingesetzt werden. Warum mit
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 24
by Claus van BeekPHP Coding Standard
Vorsicht? Die Pflicht zur Kleinschreibung macht es noch schwieriger Abkürzungen zu erkennen und
richtig zu deuten. Abkürzungen wie "cp" für "copy" dürfen niemals verwendet werden, weil der
Aufwand vier anstatt zwei Zeichen zu tippen nahezu identisch ist.
Nehmen wir an, Sie haben die Möglichkeit eine Variable "$terminal_process" oder "$tp" zu nennen.
Sie sollten immer die ausführliche Variante wählen, weil Sie mit
• Suchen & Ersetzen oder mit
• Copy & Paste
solche Variablen nicht immer wieder tippen müssen.
"$x" wird bei mathematischen Programmen und Funktionen verwendet. Das sollte allerdings nur
gemacht werden, wenn alle im Team mathematische Kenntnisse haben. Der Variablenname
"$extract_a_root" ("to extract a root" = "eine Wurzel ziehen") ist zwar nicht so kurz, aber viel
sprechender als "$x". Der Bezeichner "$root" wäre hier wieder verwirrend, weil die Variable auch
etwas mit dem Root-Account unter Linux zu tun haben könnte.
Einige Programmierer benutzen Variablen wie "$blnResult" oder "$strName", um den Typ einer
Variable zu kennzeichnen. Das ist keine gute Idee, weil einige dieser Abkürzungen einem
Programmierneuling nicht bekannt sind und selbst Google und das Wikipedia dazu keine direkten
Treffer liefern. "str" ist unter anderem eine Abkürzung für "Straße" oder den Flughafen von Stuttgart.
"bln" liefert noch verwirrendere Ergebnisse. Trotzdem werden Abkürzungen sehr häufig von
Programmierern verwendet.
Aus Erfahrung weiß ich, dass Programmierer, die sehr intensiv Abkürzungen verwenden, sich nach
mehreren Monaten selbst in ihren Source-Code einarbeiten müssen. Immer wieder tauchen Fragen
auf: "Dieses '$tp' ... was habe ich mir vor einem Jahr dabei gedacht?". Der PHP Coding Standard
sollte das Maß dieser Einarbeitung auf ein Minimum reduzieren.
Ausnahme zu Regel 11: Zählvariablen in Schleifen werden in der Regel mit einem Buchstaben ("$i",
"$j", "$k" und so weiter) definiert. Auch Abkürzungen, die in einem Team gebräuchlich sind, können
mit Vorsicht eingesetzt werden.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 25
by Claus van BeekPHP Coding Standard
15. 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.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 26
by Claus van BeekPHP Coding Standard 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. Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 27 by Claus van Beek
PHP Coding Standard
16. Regel 13: Die Klammern für eine Funktion () stehen direkt am Funktionsnamen
Das die Klammern für eine Funktion () stehen direkt am Funktionsnamen stehen, ist ein sehr
verbreiteter Standard. Wie die Parameter einer Funktion behandelt werden, ist nicht einheitlich
geregelt. Es wird empfohlen der Vorgabe von php.net zu entsprechen und Parameter ohne
Leerzeichen zu notieren, mit Ausnahme der Kommata. Der Funktionsaufruf "add(5,2)" könnte von
einem unerfahrenen Programmier falsch interpretiert werden. Hier werden zwei Parameter
übergeben, nicht eine Dezimalzahl, die in PHP mit "5.2" notiert werden würde. Auch deswegen und
aus Gründen der Übersichtlichkeit wird nach dem Komma ein Leerzeichen eingefügt, so wie es im
deutschen Schriftverkehr auch üblich ist.
Gültig
// constants for database connection
define('HOST', 'localhost');
define('USER', 'root');
define('PASSWORD', 'your_password');
define('DATABASE', 'your_database_name');
// connect the RDBMS and select database
mysql_connect(HOST, USER, PASSWORD);
$error = mysql_select_db(DATABASE);
Viele Skripte nutzen Variablen für die Festlegung von Verbindungsparametern. Konstanten haben
den Vorteil, dass sie in Funktionen benutzt werden können. Außerdem ist es für Angreifer unmöglich,
die Konstanten zu überschreiben.
Ungültig
get_user_data( $username, $password ); // incorrect: spaces next to brackets
get_user_data($username,$password); // incorrect: no space between arguments
get_user_data($a, $b); // ambiguous: what do variables $a and $b hold?
Die beiden Code-Blöcke zeigen einmal die richtige und die falsche Verwendung von Parametern und
Klammern. Ein weiterer Vorteil bei der Verwendung der richtigen Klammern ist das einfache Suchen
nach einer bestimmten Funktion. Es ist denkbar, dass "define" auch in den Kommentaren steht. Eine
Suche nach "define(" sollte in der Regel nur die Funktion zurückliefern.
Ausnahme zu Regel 12: Funktionen mit langen oder vielen Parametern; siehe dazu die nächste
Regel. Wie Klammern gesetzt werden, ist unter Programmierern eine der größten Debatten aller
Zeiten. Wenn sich das Team auf einen anderen Standard einigt, sollte dieser befolgt werden.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 28
by Claus van BeekPHP Coding Standard
17. Regel 14: Funktionen mit langen oder vielen Parametern müssen übersichtlich notiert
werden
Dies ist die Erweiterung zu Regel 12. Es wird oft notwendig sein, Funktionen mit vielen Parametern
zu benutzen und/oder lange Variablennamen zu definieren. Der Befehl mktime() enthält sechs
Parameter.
Gültig
$date_strftime = strftime(
'%a, %d. %b %Y',
mktime(
0,
0,
0,
$row['month'],
$row['day'],
$row['year']
)
);
Auf den ersten Blick ist so eine verschachtelte Struktur und die Anwendung einer Funktion mit vielen
Parametern sichtbar. Auch das die Funktion sechs Parameter hat ist über die Verteilung auf mehrere
Zeilen besser ersichtlich.
Ungültig
$date_strftime = strftime('%a, %d. %b %Y',mktime(0,0,0,$row['month'],
$row['day'],$row['year']));
Natürlich ist dieser Code kompakter, aber neben den Problemen, die Parameter zu identifizieren, ist
die Klammersetzung undeutlich. Da hier nur das Datum formatiert werden soll, gilt es über eine
eigene Funktion nachzudenken, die zum Beispiel mit "date_strftime($row['month'], $row['day'],
$row['year'])" aufgerufen wird. Damit würde man den Code dann wieder auf eine Zeile reduzieren.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 29
by Claus van BeekPHP Coding Standard
18. Regel 15: Der Code muss vom Design getrennt werden (Template Engine)
Code und Design zu trennen ist eine der wichtigsten Regeln. Klassen und Funktionen unterstützen
Sie darin modular zu programmieren. Wenn Sie jedoch HTML und PHP mischen, behindern Sie sich
bei diesem Ansatz und ihre Skripte werden automatisch unübersichtlich. Es gibt ganz einfache
Maßnahmen, wie man nur mit PHP eine Template Engine abbilden kann, ohne sich in vibTemplate
oder Smarty einzuarbeiten.
Zitat von Jörg Krause ("PHP5 - Grundlagen und Profiwissen", Seite 36 und 37)
Trennen Sie Code vom Design
Die Trennung hilft, leicht beherrschbare Programmteile zu erhalten. Die Wiederverwendbarkeit
des Codes wird gesteigert. Sie können mit Gestaltungswerkzeugen arbeiten, die
eingeschlossenen Code nicht verstehen. In großen Teams können Sie das Design von Designern
erledigen lassen und die reine Programmierarbeit Programmierern übergeben.
Zur Wiederverwendbarkeit von Design und Code
Wenn Sie etwas ändern möchten, müssen Sie es nur an einer Stelle tun. Konsistente
Gestaltungsmerkmale und Bedienerführung erleichtern den Nutzern die Navigation. Behandeln
Sie Design-Elemente als Komponenten, die Sie immer wieder verwenden.
Sie werden auch im Nachfolger "PHP5 - Grundlagen und Profiwissen" Textpassagen über Template
Engines und die Trennung von Code und Design finden. Jörg Krause stellt hier wichtige Prinzipien
der PHP-Programmierung vor:
• Arbeiten im Team
• Module bzw. modulares Programmieren
• Wiederverwendbarkeit
Mit einer Template Engine sind Sie viel besser in der Lage, diesen Dingen und dem PHP Coding
Standard entgegen zu kommen. Es ist ein unverzichtbarer Teil der PHP-Programmierung. Viele der
mir bekannten großen Projekte trennen PHP und HTML, aber nicht alle setzen dafür eine Template
Engine ein. Projekte wie das IPB lagern den HTML-Code in Funktionen aus, die dann über mehr oder
weniger eindeutige Skript-Namen gefunden werden können. Ich empfehle jedoch den Einsatz einer
Template Engine:
1. Template Engine nur mit PHP
2. vLIB: vlibTemplate, vlibDate und vlibMimeMail
3. Smarty
Sie sollten sich vorher in Ihrem Team überlegen, welche Template Engine sie einsetzen wollen. Ich
empfehle vLIB oder die "Template Engine nur mit PHP". Allerdings ist der Einsatz von Template
Engines umstritten: Warum Template Engines nicht glücklich machen.
Zitat von Jörg Krause ("PHP4 - Grundlagen und Profiwissen", Seite 193)
Die saubere Trennung von HTML-Code und Skript ist für die Lesbarkeit des Quelltextes ebenfalls
wichtig. Bei komplexen Anwendungen entsteht schnell ein Durcheinander von Befehlen, die auch
geübten Programmierern jede Chance nehmen, eine Funktion zu erkennen oder einen Fehler zu
finden.
Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 30
by Claus van BeekPHP Coding Standard Ich kann nicht oft genug betonen, wie wichtig sauberer und übersichtlicher Source-Code ist. Eine Template Engine wird für jede professionelle PHP-Applikation empfohlen. Template Engines sollten allerdings nicht eingesetzt werden, wenn mehrere Ausgabeformate erzeugt werden müssen. Beispiel: Datensätze aus MySQL sollen als Bild (GIF, PNG), HTML, Flash und PDF dargestellt werden können, dieses kann eine Template Engine nicht, weil sie nur Text (reiner Text, HTML, CSS, XML, LaTex, etc.) erzeugen kann. Einige Programmierer sagen, dass MVC (Model View Controller) bevorzugt eingesetzt werden sollte. Ich bin eher dafür, den "View" mit einer Template Engine zu unterstützen, wenn die Ausgabe der Daten in HTML oder XML erfolgen soll. Mittwoch, 15. Oktober 2008 - Copyright 2008 Seite: 31 by Claus van Beek
Sie können auch lesen
