CodingStandards/de

Latest revision as of 20:44, 5 June 2012

Wichtiger Hinweis: Mit der Bearbeitung dieser Seite, akzeptieren Sie das ihr Beitrag als Public Domain lizensiert wird. Wenn Sie das nicht wollen oder Aufgrund von Lizenzrechten nicht können, bearbeiten Sie diese Seite bitte nicht.

Languages:

English  • Deutsch

Originalquelle (für unsere Zwecke modifiziert): http://framework.zend.com/manual/en/coding-standard.html

Übersicht

Anwendungsbereich

Dieses Dokument beeinhaltet Richtlinien und Resourcen für Entwickler und Teamarbeit für WoWRoster und seinen Addons.
Die behandelten Themen sind:

• PHP Dateiformatierung
• Namenskonventionen
• Programmierstil
• Inline Dokumentation

Ziele

Gute Entwicklungsstandards sind wichtig in jedem Entwicklungsprojekt, insbesondere wenn mehrere Entwickler am selben Projekt arbeiten.
Entwicklungsstandards helfen sicherzustellen, das die Qualität des Programmcodes hoch ist, weniger Fehler hat und einfach zu warten ist.

PHP Dateiformatierung

Allgemein

Für Dateien, welche nur PHP Code enthalten, ist das schließende Tag ("?>") nicht erlaubt. Es is nicht notwendig bei PHP.
Es nicht zu benutzen, beugt ungewollten Leerzeichen in der Ausgabe vor.

Einzüge

Benutzt TAB, anstatt Leerzeichen um den Code einzurücken.

Maximale Zeilenlänge

Die maximale Zeilelänge liegt bei 80-120 Zeichen, Entwickler sollten darauf abzielen an der 80 Zeichengrenze so nah wie möglich zu bleiben.
Dies soll den Quellcode lesbarer gestalten.
Längere Zeilen werden auch akzeptiert und passieren. Wir verstehen das.

Zeilenabschluss

Zeilenabschluss ist der normale Weg für Unix Textdateien. Zeilen müssen nur mit einem Zeilenvorschub (LF) enden.
Zeilenvorschübe werden als ordinale 10, oder hexadezimal 0x0A geschrieben.

Verwende kein Wagenrücklauf (CR) wie bei Macintosh Computern (0x0D).

Verwenden auch nicht eine Wagenrücklauf / Zeilenvorschub-Kombination (CRLF) wie bei Windows (0x0D, 0x0A).

Namenskonventionen

Klassen

WoWRoster verwendet eine Klassen Namenskonvention, wobei die Namen der Klassen direkt zu den Verzeichnissen zugeordnet sind, in denen sie gespeichert sind.
Das Hauptverzeichnis des WoWRoster ist das "roster/" Verzeichnis, wo runter alle Dateien hierarchisch gespeichert werden.

Klassenname sollten nur aus alphanumerischen Zeichen bestehen.
Zahlen sind erlaubt in Klassennamen, es wird aber davon abgeraten.
Unterstriche sind nur erlaubt als Verzeichnistrenner -- der Dateiname "roster/lib/table.php" sollte die Klasse mit dem Name "Roster_Lib_Table".abbilden.

Umfasst ein Klassennamen mehr als nur ein Wort, so muss jeder erste Buchstabe jeden Wortes großgeschrieben werden.
Dauerhafte großschreibung ist nicht erlaubt. Beispiel: eine Klasse mit den Namen "Roster_PDF" ist nicht erlaubt, während "Roster_Pdf" akzeptiert wird.

Hier einige Beispiele für akzeptierte Klassennamen:

Roster_Db
Roster_View
Roster_View_Helper

WICHTIG:

Klassen, welche im Roster ausgeführt werden, aber nicht Bestandteil des Rosters sind, wie z.B. Klassen von Addon Entwicklern und nicht vom WoWRoster Dev Team, sollten nicht mit "Roster_" anfangen.

Schnittstellen

Schnittstellenklassen müssen den selben konventionen folgen wie alle anderen Klassen (siehe oben), jedoch müssen diese mit dem Wort "Interface" enden, wie in diesen Beispielen:

Zend_Log_Adapter_Interface
Zend_Controller_Dispatcher_Interface

Dateinamen

Für alle Dateien sind alphanumerische Zeichen, Unterstriche und Bindestriche zulässig.
Leerzeichen sind nicht gestattet.

Dateinamen müssen immer</a> kleingeschrieben werden.

Jede Datei die PHP Code enthält, sollte mit der Endung .php enden.
Diese Beispiele zeigen akzetable Dateinamen für die Klassennamen aus dem obigen Beispielen:

roster/lib/wowdb.php
roster/index.php
roster/lib/functions.lib.php

filterInput()
getElementById()
widgetFactory()

Konstanten müssen <u>immer komplett Großgeschrieben werden.

Zur besseren Lesbarkeit, müssen Wörter in Konstantennamen durch Unterstriche getrennt werden.
Zum Beispiel: EMBED_SUPPRESS_EMBED_EXCEPTION ist erlaubt, aber EMBED_SUPPRESSEMBEDEXCEPTION nicht.

Konstanten müssen als Klassenmitglieder definiert werden, durch die Benutzung des "const" Konstrukt.
Definieren von globalen Konstanten mit "define" ist zulässig, jedoch wird davon abgeraten.

Programmierstil

PHP Code Abgrenzung

PHP Code muss immer durch die kompletten PHP Tags abgegrenzt werden:

<?php

?>

Kurz-Tags sind niemals erlaubt. Für Dateien, die nur PHP Code enthalten, muss das schließende Tag immer weggelassen werden (Siehe auch Sektion 2.1, “Allgemein”).

Strings

String Literale

Wenn ein String keine Variabeln enthält, muss immer das Apostroph oder "einzelne Anführungszeichen" verwendet werden, um den String abzugrenzen:

$a = 'Beispiel String';

String Literale die Apostrophe enthalten

Wenn ein String, apostrophe enthält, ist es erlaubt zur Abgrenzung Anführungszeichen zu verwenden. Dies wird besonders für SQL Strings empfohlen:

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";

Dieser Syntax sollte bevorzugt werden, vor dem maskieren von Apostrophen.

Variabeln in Strings

Variablen in Strings sind in diesen zwei Arten zulässig:

$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";

Aus Gründen der Einheitlichkeit ist diese Form nicht zulässig:

$greeting = "Hello ${name}, welcome back!";

String Verkettung

Strings können durch den "." Operator, verkettet werden.
Ein Leerzeichen muss immer vor und hinter dem "." Operator, zur besseren Lesbarkeit, eingefügt werden:

$company = 'Zend' . 'Technologies';

Bei der Verkettung von Strings, ist es empfohlen den String in mehrere Zeilen umzubrechen, für die bessere Lesbarkeit. In solchen Fällen, sollte jede Zeile mit Leerzeichen eingerückt werden, bis der "." Operator unter dem "=" Operator steht.

$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";

Arrays

Numerisch indexierte Arrays

Negative zahlen sind nicht empfohlen als Indizes

Ein indiziertes Array, kann mit jeder beliebigen, nicht negativen, Nummer starten. Davon wird aber abgeraten und es wird empfohlen das alle Arrays als Basisindex die 0 benutzen.

Bei der Deklaration von indizierten Arrays mit dem array Schlüsselwort, muss nach jedem Komma ein Leerzeichen, zur besseren Lesbarkeit, folgen.

$sampleArray = array(1, 2, 3, 'Zend', 'Studio');

Auch mehrzeilige indzierte Arrays mit dem array Konstrukt sind zulässig. In diesem Fall, muss jede Zeile mit Leerzeichen aufgefüllt werden, so das der Anfang jeder Zeile wie unten angezeigt aussieht:

$sampleArray = array(
	1, 2, 3, 'Zend', 'Studio',
	$a, $b, $c,
	56.44, $d, 500
);

Assoziative Arrays

Wenn ein assoziatives Array deklariert wird, ist es empfohlen für jeden Eintrag eine eigene Zeile zu benutzen.
In diesem Fall sollte jede Zeile mit Leerzeichen aufgefüllt werden so das die Schlüssel und Werte in jeder Zeile untereinander stehen:

$sampleArray = array(
	'firstKey'  => 'firstValue',
	'secondKey' => 'secondValue'
);

Klassen

Klassen Deklaration

Klassen müssen nach der folgenden Konvention benannt werden.

Die Klammer wird immer in der Zeile unter dem Klassennamen ("one true brace" form) geschrieben.

Jede Klasse muss einen Dokumentationsblock besitzen, welche dem PHPDocumentator Standard entspricht

Jeder Programmcode innerhalb der Klasse muss mit TAB eingerückt werden.

Es ist nur eine Klasse pro PHP Datei erlaubt.

Weitere Programmcode in der Klassendatei ist erlaubt, aber nicht gern gesehen.
In diesen Dateien müssen zwei Leerzeilen die Klasse von dem weiteren PHP Code in der Datei trennen.

Hier ein Beispiel für akzeptierte Klassen Deklaration:

/**
 * Documentation Block Here
 */
class SampleClass
{
	// entire content of class
	// must be indented four spaces
}

Klassen Variabeln

Klassenvariabeln müssen den Namenskonventionen folgen.

Jede in der Klasse deklarierte Variable muss im Kopf der Klasse aufgelistet werden, vor allen Funktionen.

Von dem direkte Zugriff auf Klassenvariablen (von ausserhalb), durch das setzen auf "public", wird abgeraten, zu Gunsten der Zugriffsmethoden Variablen (set / get).

Funktionen und Methoden

Deklaration von Funktionen und Methoden

Funktionen müssen den Namenskonventionen folgen.

Wie bei Klassen, müssen die Klammern immer unterhalb des Funktionsnamen geschrieben werden ("one true brace" form).
Es gibt keine Leerzeichen zwischen dem Funktionsnamen und den Klammern für die Funktionsargumente.

Von globale Funktionen wird dringend abgeraten.

Hier ein Beispiel für akzeptierte Funktionsdeklarartion in einer Klasse:

/**
 * Documentation Block Here
 */
class Foo
{
	/**
	 * Documentation Block Here
	 */
	function bar()
	{
		// entire content of function
		// must be indented using tabs
	}
}

HINWEIS: Die Übergabe als Referenz ist nur in der Funktionsdeklaration zulässig:

/**
 * Documentation Block Here
 */
class Foo
{
	/**
	 * Documentation Block Here
	 */
	function bar(&$baz)
	{
		// entire content of function
		// must be indented using tabs
	}
}

Der Aufruf zur Laufzeit ist untersagt.

Der Rückgabewert muss nicht in Klammern eingeschlossen werden. Dies kann die Lesbarkeit und den Programmcode stören, wenn die Methode später geändert wird um eine Referenz zurückzugeben.

/**
 * Documentation Block Here
 */
class Foo
{
	/**
	 * WRONG
	 */
	function bar()
	{
		return($this->bar);
	}

	/**
	 * RIGHT
	 */
	function bar()
	{
	return $this->bar;
	}
}

Benutzung von Funktionen und Methoden

Funktionsargumente sind durch ein einzelnes Leerzeichen nach dem Komma zu trennen.
Hier ein Beispiel für einen akzeptierten Funktionsaufruf mit drei Argumenten:

threeArguments(1, 2, 3);

Das aufrufen zur Laufzeit ist verboten.

Siehe den Abschnitt Funktionsdeklaration für den richtigen Weg, um Funktionsargumente als Referenz zu übergeben.

Für Funktionen deren Argumente arrays erlauben, darf der Funktionsaufruf das array Konstrukt beeinhalten und kann auf mehrere Zeilen, zur besseren Lesbarkeit, aufgeteilt werden..
In diesen Fällen gelten die Standards für das Schreiben von Arrays immer noch:

threeArguments(array(1, 2, 3), 2, 3);

threeArguments(
	array(
		1, 2, 3, 'Zend', 'Studio',
		$a, $b, $c,
		56.44, $d, 500
	), 2, 3
);

Steueranweisungen

If / Else / Elseif

Steueranweisungen die auf den if und elseif Konstrukten basieren, müssen ein einzelnes Leerzeichen nach den geöffneten bzw. vor den geschlossenen Klammern beeinhalten.

Innerhalb der Bedingungsanweisungen müssen zwischen den Klammern Operatoren durch Leerzeichen separiert werden, für eine bessere Lesbarkeit.
Innere Klammern sollten benutzt werden um logische Bedingungen zu gruppieren.

Die geöffnete Klammer wird immer unter die Zeile mit dem Steueranweisungen geschrieben ("one true brace" form).
Die geschlossen Klammer wird immer in eine eigene Zeile geschrieben.
Jeder Inhalt innerhalb der Klammern muss durch TAB eingerückt werden.

if( $a != 2 )
{
	$a = 2;
}

Für "if" Anweisungen, welche "elseif" oder "else" enthalten, muss die Formatierung wie in folgenden Beispielen sein:

if( $a != 2 )
{
	$a = 2;
}
else
{
	$a = 7;
}

if( $a != 2 )
{
	$a = 2;
}
elseif( $a == 3 )
{
	$a = 4;
}
else
{
	$a = 7;
}

PHP erlaubt es in bestimmten Fällen die Klammern wegzulassen.
Die Richtlinien machen da keinen Unterschied und alle "if", "elseif" oder "else" Anweisungen müssen mit Klammern geschrieben werden.

Die Benutzung von "else if" Konstrukten ist zulässig, davon wird aber dringend abgeraten und es sollte stattdessen "elseif" benutzt werden.

Switch

Steueranweisungen in dem "switch" Konstrukt sollten immer ein Leerzeichen vor bzw. nach der Klammer haben.

Jeder Inhalt innerhalb des "switch" Konstruktes muss durch ein TAB eingerückt werden.
Inhalte unter der "case" Anweisung muss ebenfalls mit einem weiteren TAB eingerückt werden.

switch( $numPeople )
{
	case 1:
		break;

	case 2:
		break;

	default:
		break;
}

Die "default" Anweisung muss immer enthalten sein.

{{note:Manchmal ist es nützlich eine "case" Anweisungen zu schreiben die nacheinander aufgerufen werden, ohne break oder return.
Um dies Fälle von Fehlern zu unterscheiden, muss diese mit dem Kommentar "// break intentionally omitted" (break absichtlich weggelassen) versehen werden.}}

Inline Dokumentation

Dokumenationsformat

Alle Dokumentationsblöcke ("docblocks") müssen mit dem phpDocumentator Format kompatibel sein.
Die Beschreibung des phpDocumentor Format liegt ausserhalb des Rahmen dieses Dokuments.
Für weitere Informationen, gehe auf: [1]

Jeder Quellcodedatei die für den WoWRoster geschrieben wurde oder die im WoWRoster arbeitet muss einen "file-level" Docblock oben in der Datei enthalten und ein "class-level" Docblock unmittelbar über jeder Klasse.
Unten sind einige Beispiele für solche Docblocks.

Dateien

Jede Datei die PHP Code beeinhaltet muss einen Kopfblock am Anfang der Datei haben, welcher mindestens folgende phpDocumentor Tags beeinhaltet:

/**
 * Kurzbeschreibung der Datei
 *
 * Lange Beschreibung der Datei (wenn es eine gibt)...
 *
 * LICENSE: Einige Lizenzinformationen
 *
 * @copyright  2007 WoWRoster.net
 * @license    http://creativecommons.org/licenses/by-nc-sa/2.5   Attribution-NonCommercial-ShareAlike 2.5
 * @version    SVN: $Id: $
 * @link       http://www.wowroster.net
 * @since      File available since Release 1.7.0
*/

Klassen

Jede Klasse muss einen Docblock haben, welcher mindestens folgende phpDocumentor Tags enthält:

/**
 * Kurzbeschreibung der Klasse
 *
 * Lange Beschreibung der Klasse (wenn es eine gibt)...
 *
 * @copyright  2007 WoWRoster.net
 * @license    http://creativecommons.org/licenses/by-nc-sa/2.5   Attribution-NonCommercial-ShareAlike 2.5
 * @version    Release: package_version
 * @link       http://www.wowroster.net
 * @since      Class available since Release 1.7.0
 * @deprecated Class deprecated in Release 2.0.0
 */

Funktionen

Jede Funktion, Objektmethoden einbezogen, müssen einen Docblock haben der mindestens folgendes enthält:

• Eine Beschreibung der Funktion
• Alle Argumente der Funktion
• Alle möglichen Rückgabewerte