Coding Standard
***************
.[perex]
Dieses Dokument beschreibt die Regeln und Empfehlungen für die Entwicklung von Nette. Wenn Sie Code zu Nette beisteuern, müssen Sie sich an sie halten. Am einfachsten gelingt das, indem Sie den bestehenden Code nachahmen. Das Ziel ist, dass der gesamte Code so aussieht, als hätte ihn eine einzige Person geschrieben.
Der Nette Coding Standard entspricht dem [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] mit zwei wesentlichen Ausnahmen: Zum Einrücken verwendet er [Tabulatoren statt Leerzeichen |#Tabulatoren statt Leerzeichen] und für Klassenkonstanten [PascalCase|https://blog.nette.org/de/for-less-screaming-in-the-code].
.[tip]
Viele dieser Regeln kann das Werkzeug [Nette Coding Standard |tools:coding-standard] automatisch prüfen und korrigieren, Sie müssen sie also nicht von Hand kontrollieren.
Allgemeine Regeln
=================
- Jede PHP-Datei muss `declare(strict_types=1)` enthalten
- Zur besseren Lesbarkeit werden Methoden durch zwei Leerzeilen getrennt
- Der Grund für die Verwendung des Fehlerunterdrückungsoperators (`@`) muss dokumentiert werden: `@mkdir($dir); // @ - directory may exist`
- Wird ein schwach typisierter Vergleichsoperator verwendet (also `==`, `!=`, ...), muss die Absicht dokumentiert werden: `// == to accept null`
- Mehrere Exception-Klassen dürfen Sie in eine einzige Datei namens `exceptions.php` schreiben, mehrere Enums in `enums.php`
- Bei Interfaces wird die Sichtbarkeit von Methoden nicht angegeben, denn sie sind immer public
- Jede Property, jeder Rückgabewert und jeder Parameter muss einen Typ angegeben haben. Umgekehrt geben wir bei finalen Konstanten den Typ nie an, weil er offensichtlich ist
- Zum Begrenzen von Strings sollen einfache Anführungszeichen verwendet werden, außer wenn das Literal selbst Apostrophe enthält
Benennungskonventionen
======================
- Vermeiden Sie Abkürzungen, sofern der volle Name nicht zu ausufernd wird
- Verwenden Sie bei zweibuchstabigen Abkürzungen Großbuchstaben, bei längeren Abkürzungen PascalCase/camelCase
- Verwenden Sie für den Klassennamen ein Substantiv oder eine Substantivgruppe
- Klassennamen müssen nicht nur das Besondere (`Array`), sondern auch das Allgemeine (`ArrayIterator`) enthalten. PHP-Attribute sind eine Ausnahme
- "Klassenkonstanten und Enums sollten PascalCaps verwenden":https://blog.nette.org/de/for-less-screaming-in-the-code
- "Interfaces und abstrakte Klassen sollten keine Präfixe oder Suffixe enthalten":https://blog.nette.org/de/prefixes-and-suffixes-do-not-belong-in-interface-names wie `Abstract`, `Interface` oder `I`
Umbrüche und Klammern
=====================
Der Nette Coding Standard entspricht PSR-12 (bzw. dem PER Coding Style), präzisiert oder verändert ihn aber in einigen Punkten:
- Arrow-Funktionen werden ohne Leerzeichen vor der Klammer geschrieben, also `fn($a) => $b`
- Zwischen verschiedenen Arten von `use`-Import-Anweisungen ist keine Leerzeile nötig
- Der Rückgabetyp einer Funktion/Methode und die öffnende geschweifte Klammer stehen immer in getrennten Zeilen:
```php
public function find(
string $dir,
array $options,
): array
{
// Rumpf der Methode
}
```
Die öffnende geschweifte Klammer in einer eigenen Zeile ist wichtig, um die Signatur der Funktion/Methode optisch vom Rumpf zu trennen. Steht die Signatur in einer Zeile, ist die Trennung deutlich (Bild links), erstreckt sie sich über mehrere Zeilen, verschmelzen Signatur und Rumpf bei PSR miteinander (Mitte), während sie im Nette-Standard weiterhin getrennt bleiben (rechts):
[* new-line-after.webp *]
Dokumentationsblöcke (phpDoc)
=============================
Die Hauptregel: **Wiederholen Sie niemals** Informationen aus der Signatur wie Parametertyp oder Rückgabetyp, ohne einen Mehrwert zu schaffen.
Dokumentationsblock für eine Klassendefinition:
- Beginnt mit einer Beschreibung der Klasse
- Danach folgt eine Leerzeile
- Danach folgen Annotationen `@property` (oder `@property-read`, `@property-write`), eine pro Zeile. Syntax: Annotation, Leerzeichen, Typ, Leerzeichen, `$name`
- Danach folgen Annotationen `@method`, eine pro Zeile. Syntax: Annotation, Leerzeichen, Rückgabetyp, Leerzeichen, `name(type $param, ...)`
- Die Annotation `@author` entfällt. Die Autorschaft wird in der Historie des Quellcodes geführt
- Die Annotationen `@internal` oder `@deprecated` dürfen verwendet werden
```php
/**
* MIME message part.
*
* @property string $encoding
* @property-read array $headers
* @method string getSomething(string $name)
* @method static bool isEnabled()
*/
```
Ein Dokumentationsblock für eine Property, der nur die Annotation `@var` enthält, soll einzeilig sein:
```php
/** @var string[] */
private array $name;
```
Dokumentationsblock für eine Methodendefinition:
- Beginnt mit einer kurzen Beschreibung der Methode
- Keine Leerzeile
- Annotationen `@param`, eine pro Zeile
- Annotation `@return`
- Annotationen `@throws`, eine pro Zeile
- Die Annotationen `@internal` oder `@deprecated` dürfen verwendet werden
Nach jeder Annotation folgt ein Leerzeichen, außer bei `@param`, nach der zur besseren Lesbarkeit zwei Leerzeichen folgen.
```php
/**
* Finds a file in directory.
* @param string[] $options
* @return string[]
* @throws DirectoryNotFoundException
*/
public function find(string $dir, array $options): array
```
Globale Funktionen und Konstanten
=================================
Globale Funktionen und Konstanten werden ohne führenden Backslash geschrieben, also `count($arr)` und nicht `\count($arr)`. Bei Funktionen, die PHP optimieren kann, ergänzen Sie am Anfang der Datei `use function`, damit der Compiler sie effizienter übersetzen kann. Dazu gehören Funktionen wie `count`, `strlen`, `is_array`, `is_string`, `is_scalar`, `sprintf` usw. Die Funktionen werden in einer einzigen Zeile aufgeführt, damit der Import-Block kompakt bleibt:
```php
use Nette;
use function count, is_array, is_scalar, sprintf;
```
Gelegentlich importieren wir auch Konstanten, bei denen die Kenntnis ihres Wertes dem Compiler helfen kann:
```php
use const PHP_OS_FAMILY;
```
Tabulatoren statt Leerzeichen
=============================
Tabulatoren haben gegenüber Leerzeichen mehrere Vorteile:
- Die Größe der Einrückung lässt sich in Editoren und im "Web":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size einstellen
- Sie zwingen dem Code nicht die bevorzugte Einrückungsgröße des Benutzers auf, wodurch der Code portabler wird
- Sie lassen sich mit einem einzigen Tastendruck eingeben (überall, nicht nur in Editoren, die Tabulatoren in Leerzeichen umwandeln)
- Einrücken ist ihr Zweck
- Sie berücksichtigen die Bedürfnisse sehbehinderter und blinder Kollegen
Indem wir in unseren Projekten Tabulatoren verwenden, ermöglichen wir eine Anpassung der Breite, die den meisten Menschen unnötig erscheinen mag, für Menschen mit Sehbehinderung aber wesentlich ist.
Für blinde Programmierer, die Braillezeilen verwenden, steht jedes Leerzeichen für eine Braillezelle. Beträgt die Standardeinrückung also 4 Leerzeichen, verschwendet eine Einrückung der 3. Ebene 12 wertvolle Braillezellen, bevor der Code überhaupt beginnt. Auf einer Zeile mit 40 Zellen, wie sie bei Laptops am häufigsten ist, ist das mehr als ein Viertel der verfügbaren Zellen, das ohne jede Information verschwendet wird.
{{priority: -1}}
Coding Standard
Dieses Dokument beschreibt die Regeln und Empfehlungen für die Entwicklung von Nette. Wenn Sie Code zu Nette
beisteuern, müssen Sie sich an sie halten. Am einfachsten gelingt das, indem Sie den bestehenden Code nachahmen. Das Ziel ist,
dass der gesamte Code so aussieht, als hätte ihn eine einzige Person geschrieben.
Viele dieser Regeln kann das Werkzeug Nette Coding
Standard automatisch prüfen und korrigieren, Sie müssen sie also nicht von Hand kontrollieren.
Allgemeine Regeln
Jede PHP-Datei muss declare(strict_types=1) enthalten
Zur besseren Lesbarkeit werden Methoden durch zwei Leerzeilen getrennt
Der Grund für die Verwendung des Fehlerunterdrückungsoperators (@) muss dokumentiert werden:
@mkdir($dir); // @ - directory may exist
Wird ein schwach typisierter Vergleichsoperator verwendet (also ==, !=, …), muss die Absicht
dokumentiert werden: // == to accept null
Mehrere Exception-Klassen dürfen Sie in eine einzige Datei namens exceptions.php schreiben, mehrere Enums in
enums.php
Bei Interfaces wird die Sichtbarkeit von Methoden nicht angegeben, denn sie sind immer public
Jede Property, jeder Rückgabewert und jeder Parameter muss einen Typ angegeben haben. Umgekehrt geben wir bei finalen
Konstanten den Typ nie an, weil er offensichtlich ist
Zum Begrenzen von Strings sollen einfache Anführungszeichen verwendet werden, außer wenn das Literal selbst Apostrophe
enthält
Benennungskonventionen
Vermeiden Sie Abkürzungen, sofern der volle Name nicht zu ausufernd wird
Verwenden Sie bei zweibuchstabigen Abkürzungen Großbuchstaben, bei längeren Abkürzungen PascalCase/camelCase
Verwenden Sie für den Klassennamen ein Substantiv oder eine Substantivgruppe
Klassennamen müssen nicht nur das Besondere (Array), sondern auch das Allgemeine (ArrayIterator)
enthalten. PHP-Attribute sind eine Ausnahme
Der Nette Coding Standard entspricht PSR-12 (bzw. dem PER Coding Style), präzisiert oder verändert ihn aber in einigen
Punkten:
Arrow-Funktionen werden ohne Leerzeichen vor der Klammer geschrieben, also fn($a) => $b
Zwischen verschiedenen Arten von use-Import-Anweisungen ist keine Leerzeile nötig
Der Rückgabetyp einer Funktion/Methode und die öffnende geschweifte Klammer stehen immer in getrennten Zeilen:
public function find(
string $dir,
array $options,
): array
{
// Rumpf der Methode
}
Die öffnende geschweifte Klammer in einer eigenen Zeile ist wichtig, um die Signatur der Funktion/Methode optisch vom Rumpf zu
trennen. Steht die Signatur in einer Zeile, ist die Trennung deutlich (Bild links), erstreckt sie sich über mehrere Zeilen,
verschmelzen Signatur und Rumpf bei PSR miteinander (Mitte), während sie im Nette-Standard weiterhin getrennt bleiben
(rechts):
Dokumentationsblöcke (phpDoc)
Die Hauptregel: Wiederholen Sie niemals Informationen aus der Signatur wie Parametertyp oder Rückgabetyp, ohne einen
Mehrwert zu schaffen.
Dokumentationsblock für eine Klassendefinition:
Beginnt mit einer Beschreibung der Klasse
Danach folgt eine Leerzeile
Danach folgen Annotationen @property (oder @property-read, @property-write), eine pro
Zeile. Syntax: Annotation, Leerzeichen, Typ, Leerzeichen, $name
Danach folgen Annotationen @method, eine pro Zeile. Syntax: Annotation, Leerzeichen, Rückgabetyp, Leerzeichen,
name(type $param, ...)
Die Annotation @author entfällt. Die Autorschaft wird in der Historie des Quellcodes geführt
Die Annotationen @internal oder @deprecated dürfen verwendet werden
Ein Dokumentationsblock für eine Property, der nur die Annotation @var enthält, soll einzeilig sein:
/** @var string[] */
private array $name;
Dokumentationsblock für eine Methodendefinition:
Beginnt mit einer kurzen Beschreibung der Methode
Keine Leerzeile
Annotationen @param, eine pro Zeile
Annotation @return
Annotationen @throws, eine pro Zeile
Die Annotationen @internal oder @deprecated dürfen verwendet werden
Nach jeder Annotation folgt ein Leerzeichen, außer bei @param, nach der 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
Globale Funktionen und Konstanten
Globale Funktionen und Konstanten werden ohne führenden Backslash geschrieben, also count($arr) und nicht
\count($arr). Bei Funktionen, die PHP optimieren kann, ergänzen Sie am Anfang der Datei use function,
damit der Compiler sie effizienter übersetzen kann. Dazu gehören Funktionen wie count, strlen,
is_array, is_string, is_scalar, sprintf usw. Die Funktionen werden in einer
einzigen Zeile aufgeführt, damit der Import-Block kompakt bleibt:
use Nette;
use function count, is_array, is_scalar, sprintf;
Gelegentlich importieren wir auch Konstanten, bei denen die Kenntnis ihres Wertes dem Compiler helfen kann:
use const PHP_OS_FAMILY;
Tabulatoren statt Leerzeichen
Tabulatoren haben gegenüber Leerzeichen mehrere Vorteile:
Die Größe der Einrückung lässt sich in Editoren und im Web einstellen
Sie zwingen dem Code nicht die bevorzugte Einrückungsgröße des Benutzers auf, wodurch der Code portabler wird
Sie lassen sich mit einem einzigen Tastendruck eingeben (überall, nicht nur in Editoren, die Tabulatoren in Leerzeichen
umwandeln)
Einrücken ist ihr Zweck
Sie berücksichtigen die Bedürfnisse sehbehinderter und blinder Kollegen
Indem wir in unseren Projekten Tabulatoren verwenden, ermöglichen wir eine Anpassung der Breite, die den meisten Menschen
unnötig erscheinen mag, für Menschen mit Sehbehinderung aber wesentlich ist.
Für blinde Programmierer, die Braillezeilen verwenden, steht jedes Leerzeichen für eine Braillezelle. Beträgt die
Standardeinrückung also 4 Leerzeichen, verschwendet eine Einrückung der 3. Ebene 12 wertvolle Braillezellen, bevor der Code
überhaupt beginnt. Auf einer Zeile mit 40 Zellen, wie sie bei Laptops am häufigsten ist, ist das mehr als ein Viertel der
verfügbaren Zellen, das ohne jede Information verschwendet wird.