Kodierungsstandard

Dieses Dokument beschreibt Regeln und Empfehlungen für die Entwicklung von Nette. Wenn Sie Code zu Nette beisteuern, müssen Sie diese befolgen. Der einfachste Weg, dies zu tun, ist, den vorhandenen Code zu imitieren. Die Idee ist, den gesamten Code so aussehen zu lassen, als wäre er von einer Person geschrieben worden.

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

Allgemeine Regeln

• Jede PHP-Datei muss enthalten declare(strict_types=1)
• Zur besseren Lesbarkeit werden die Methoden durch zwei Leerzeilen getrennt.
• Der Grund für die Verwendung des shut-up-Operators muss dokumentiert werden: @mkdir($dir); // @ - directory may exist
• Wenn ein schwach typisierter Vergleichsoperator verwendet wird (z. B. ==, !=, …), muss die Absicht dokumentiert werden: // == to accept null
• Sie können mehrere Ausnahmen in eine Datei schreiben exceptions.php
• Die Sichtbarkeit von Methoden wird bei Schnittstellen nicht angegeben, da sie immer öffentlich sind.
• Für jede Eigenschaft, jeden Rückgabewert und jeden Parameter muss ein Typ angegeben werden. Bei endgültigen Konstanten hingegen wird der Typ nicht angegeben, da er offensichtlich ist.
• Einfache Anführungszeichen sollten zur Abgrenzung der Zeichenkette verwendet werden, es sei denn, das Literal selbst enthält Apostrophe.

Benennungskonventionen

• Vermeiden Sie die Verwendung von Abkürzungen, es sei denn, der vollständige Name ist zu lang.
• Verwenden Sie Großbuchstaben für zweibuchstabige Abkürzungen und Klein-/Kleinschreibung für längere Abkürzungen.
• Verwenden Sie ein Substantiv oder eine Substantivphrase als Klassenname.
• Klassennamen müssen nicht nur die Besonderheit (Array), sondern auch die Allgemeinheit (ArrayIterator) enthalten. Die Ausnahme sind PHP-Attribute.
• Klassenkonstanten und Enums sollten PascalCaps verwenden.
• Schnittstellen und abstrakte Klassen sollten keine Präfixe oder Postfixe enthalten wie Abstract, Interface oder I.

Wrapping und Klammern

Nette Coding Standard entspricht der PSR-12 (oder PER Coding Style), in einigen Punkten spezifiziert er sie weiter oder modifiziert sie:

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

	public function find(
		string $dir,
		array $options,
	): array
	{
		// method body
	}

Die öffnende geschweifte Klammer in einer separaten Zeile ist wichtig, um die Funktions-/Methodensignatur visuell vom Körper zu trennen. Wenn die Signatur in einer Zeile steht, ist die Trennung klar (Bild links), wenn sie in mehreren Zeilen steht, verschmelzen in PSR die Signaturen und Körper miteinander (in der Mitte), während sie im Nette-Standard getrennt bleiben (rechts):

Dokumentationsblöcke (phpDoc)

Die wichtigste Regel: Duplizieren Sie niemals Signaturinformationen wie Parametertyp oder Rückgabetyp ohne zusätzlichen Wert.

Dokumentationsblock für die Klassendefinition:

• Beginnt mit einer Klassenbeschreibung.
• Es folgt eine leere Zeile.
• Es folgen die Anmerkungen @property (oder @property-read, @property-write), eine nach der anderen. Die Syntax lautet: annotation, space, type, space, $name.
• Es folgen die @method Anmerkungen, eine nach der anderen. Die Syntax lautet: annotation, space, return type, space, name(type $param, …).
• Die @author -Anmerkung wird weggelassen. Die Urheberschaft wird in einer Quellcode-Historie festgehalten.
• Die Anmerkungen @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()
 */

Der Dokumentationsblock für eine Eigenschaft, die nur den Vermerk @var enthält, sollte aus einer einzigen Zeile bestehen:

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

Dokumentationsblock für Methodendefinition:

• Beginnt mit einer kurzen Methodenbeschreibung.
• Keine Leerzeile.
• Die @param Annotationen, eine nach der anderen.
• Die @return -Anmerkung.
• Die @throws -Anmerkungen, eine nach der anderen.
• Die Anmerkungen @internal oder @deprecated können verwendet werden.

Nach jeder Anmerkung folgt ein Leerzeichen, mit Ausnahme der Anmerkung @param, die zur besseren Lesbarkeit mit zwei Leerzeichen versehen ist.

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

Tabulatoren anstelle von Leerzeichen

Tabulatoren haben mehrere Vorteile gegenüber Leerzeichen:

• die Größe der Einrückung ist in Editoren und im Web anpassbar
• sie zwingen dem Code nicht die vom Benutzer bevorzugte Einrückungsgröße auf, so dass der Code besser portabel ist
• man kann sie mit einem Tastendruck eingeben (überall, nicht nur in Editoren, die Tabulatoren in Leerzeichen umwandeln)
• die Einrückung ist ihr Zweck
• die Bedürfnisse von sehbehinderten und blinden Kollegen zu respektieren

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

Für blinde Programmierer, die Braillezeilen verwenden, wird jedes Leerzeichen durch eine Braille-Zelle dargestellt und nimmt wertvollen Platz in Anspruch. Wenn also die Standardeinrückung 4 Leerzeichen beträgt, verschwendet eine Einrückung der dritten Ebene 12 Braille-Zellen, bevor der Code beginnt. Auf einer 40-Zellen-Anzeige, die am häufigsten auf Laptops verwendet wird, ist das mehr als ein Viertel der verfügbaren Zellen, die ohne jegliche Information verschwendet werden.