Codierungsstandard

Dieses Dokument beschreibt die Regeln und Empfehlungen für die Entwicklung von Nette. Wenn Sie Code zu Nette beitragen, müssen Sie diese einhalten. Der einfachste Weg, dies zu tun, ist, den vorhandenen Code nachzuahmen. Ziel ist es, dass der gesamte Code so aussieht, als wäre er von einer einzigen Person geschrieben worden.

Der Nette Coding Standard entspricht dem PSR-12 Extended Coding Style mit zwei Hauptausnahmen: Er verwendet Tabulatoren statt Leerzeichen für die Einrückung und PascalCase für Klassenkonstanten.

Allgemeine Regeln

• Jede PHP-Datei muss declare(strict_types=1) enthalten.
• Zwei Leerzeilen werden verwendet, um Methoden zur besseren Lesbarkeit voneinander zu trennen.
• Der Grund für die Verwendung des Shut-up-Operators muss dokumentiert werden: @mkdir($dir); // @ - Verzeichnis kann existieren.
• Wenn ein schwach typisierter Vergleichsoperator verwendet wird (d. h. ==, !=, …), muss die Absicht dokumentiert werden: // == null akzeptieren
• In eine einzige Datei exceptions.php können mehrere Ausnahmen geschrieben werden.
• Bei Schnittstellen wird die Sichtbarkeit von Methoden nicht angegeben, da sie immer öffentlich sind.
• Jede Eigenschaft, jeder Rückgabewert und jeder Parameter muss einen Typ angegeben haben. Bei finalen Konstanten geben wir den Typ jedoch nie an, da er offensichtlich ist.
• Zum Begrenzen von Zeichenketten sollten einfache Anführungszeichen verwendet werden, es sei denn, das Literal selbst enthält Apostrophe.

Benennungskonventionen

• Verwenden Sie keine Abkürzungen, es sei denn, der vollständige Name ist zu lang.
• Verwenden Sie bei zweibuchstabigen Abkürzungen Großbuchstaben, bei längeren Abkürzungen Pascal/CamelCase.
• Verwenden Sie für den Klassennamen ein Substantiv oder eine Wortgruppe.
• Klassennamen müssen nicht nur die Spezifität (Array), sondern auch die Allgemeinheit (ArrayIterator) enthalten. Ausnahmen sind PHP-Sprachattribute.
• Klassenkonstanten und Enums sollten PascalCaps verwenden.
• Schnittstellen und abstrakte Klassen sollten keine Präfixe oder Suffixe enthalten wie Abstract, Interface oder I.

Umbrüche und Klammern

Der Nette Coding Standard entspricht PSR-12 (bzw. PER Coding Style), ergänzt oder modifiziert ihn jedoch in einigen Punkten:

• Pfeilfunktionen werden ohne Leerzeichen vor der Klammer geschrieben, d.h. fn($a) => $b
• Es ist keine Leerzeile zwischen verschiedenen Typen von use-Importanweisungen erforderlich.
• Der Rückgabetyp einer Funktion/Methode und die öffnende geschweifte Klammer stehen immer auf separaten Zeilen:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// Methodenkörper
	}

Die öffnende geschweifte Klammer auf einer separaten Zeile ist wichtig für die visuelle Trennung der Signatur der Funktion/Methode vom Körper. Wenn die Signatur auf einer Zeile steht, ist die Trennung deutlich (Bild links), wenn sie auf mehreren Zeilen steht, verschmelzen in PSR Signatur und Körper (Mitte), während sie im Nette-Standard weiterhin getrennt sind (rechts):

Dokumentationsblöcke (phpDoc)

Hauptregel: Duplizieren Sie niemals Informationen in der Signatur, wie den Parametertyp oder den Rückgabetyp, ohne Mehrwert.

Dokumentationsblock für die Klassendefinition:

• Beginnt mit der Beschreibung der Klasse.
• Gefolgt von einer Leerzeile.
• Gefolgt von @property-Annotationen (oder @property-read, @property-write), eine nach der anderen. Syntax: Annotation, Leerzeichen, Typ, Leerzeichen, $Name.
• Gefolgt von @method-Annotationen, eine nach der anderen. Syntax: Annotation, Leerzeichen, Rückgabetyp, Leerzeichen, Name(Typ $param, …).
• Die @author-Annotation wird weggelassen. Die Autorschaft wird in der Quellcode-Historie gespeichert.
• Die Annotationen @internal oder @deprecated können verwendet werden.

/**
 * MIME message part.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */

Ein Dokumentationsblock für eine Eigenschaft, der nur die Annotation @var enthält, sollte einzeilig sein:

/** @var string[] */
private array $name;

Dokumentationsblock für die Methodendefinition:

• Beginnt mit einer kurzen Beschreibung der Methode.
• Keine Leerzeile.
• @param-Annotationen in einzelnen Zeilen.
• @return-Annotation.
• @throws-Annotationen, eine nach der anderen.
• Die Annotationen @internal oder @deprecated können verwendet werden.

Auf jede Annotation folgt ein Leerzeichen, mit Ausnahme von @param, auf das zur besseren Lesbarkeit zwei Leerzeichen folgen.

/**
 * Finds a file in directory.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Tabulatoren statt Leerzeichen

Tabulatoren haben gegenüber Leerzeichen mehrere Vorteile:

• Die Größe des Abstands kann in Editoren und im Web angepasst werden.
• Sie zwingen dem Code nicht die vom Benutzer bevorzugte Einrückungsgröße auf, sodass der Code besser portierbar ist.
• Sie können mit einem einzigen Tastendruck geschrieben werden (überall, nicht nur in Editoren, die Tabulatoren in Leerzeichen umwandeln).
• Einrückung ist ihr Sinn.
• Sie respektieren die Bedürfnisse von sehbehinderten und blinden Kollegen.

Durch die Verwendung von Tabulatoren in unseren Projekten ermöglichen wir die Anpassung der Breite, was den meisten Menschen als unnötig erscheinen mag, aber für Menschen mit Sehbehinderungen unerlässlich ist.

Für blinde Programmierer, die Braillezeilen verwenden, stellt jedes Leerzeichen eine Braillezelle dar. Wenn also die Standardeinrückung 4 Leerzeichen beträgt, verschwendet die Einrückung der 3. Ebene 12 wertvolle Braillezellen, noch bevor der Code beginnt. Auf einem 40-Zellen-Display, das bei Laptops am häufigsten verwendet wird, ist das mehr als ein Viertel der verfügbaren Zellen, die ohne jegliche Information verschwendet werden.