Standard kodowania
******************

.[perex]
Ten dokument opisuje reguły i zalecenia dotyczące rozwoju Nette. Kontrybuując kod do Nette, musisz się do nich stosować. Najprościej zrobisz to, naśladując istniejący kod. Celem jest, żeby cały kod wyglądał tak, jakby napisała go jedna osoba.

Standard kodowania Nette odpowiada [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] z dwoma głównymi wyjątkami: do wcięć używa [tabulatorów zamiast spacji |#Tabulatory zamiast spacji] i używa [PascalCase dla stałych klas|https://blog.nette.org/en/for-less-screaming-in-the-code].

.[tip]
Wiele z tych reguł da się automatycznie sprawdzić i poprawić narzędziem [Nette Coding Standard |tools:coding-standard], więc nie musisz sprawdzać ich ręcznie.


Reguły ogólne
=============

- Każdy plik PHP musi zawierać `declare(strict_types=1)`
- Do oddzielenia metod używa się dwóch pustych linii dla lepszej czytelności
- Powód użycia operatora wyciszającego (`@`) musi być udokumentowany: `@mkdir($dir); // @ - directory may exist`
- Jeśli używany jest operator porównania słabo typowany (czyli `==`, `!=`, ...), intencja musi być udokumentowana: `// == to accept null`
- Wiele klas wyjątków możesz zapisać do jednego pliku o nazwie `exceptions.php`, a wiele enumów do `enums.php`
- Widoczności metod nie podaje się dla interfejsów, bo zawsze są publiczne
- Każda właściwość, wartość zwracana i parametr muszą mieć podany typ. Odwrotnie, dla stałych finalnych typu nigdy nie podajemy, bo jest oczywisty
- Do ograniczania ciągów należy używać apostrofów, z wyjątkiem sytuacji, gdy sam literał zawiera apostrofy


Konwencje nazewnicze
====================

- Unikaj używania skrótów, chyba że pełna nazwa jest nadmierna
- Dla skrótów dwuliterowych używaj wielkich liter, a dla dłuższych PascalCase/camelCase
- Na nazwę klasy używaj rzeczownika albo frazy rzeczownikowej
- Nazwy klas muszą zawierać nie tylko konkret (`Array`), ale też ogólność (`ArrayIterator`). Wyjątkiem są atrybuty PHP
- "Stałe klas i enumy powinny używać PascalCaps":https://blog.nette.org/en/for-less-screaming-in-the-code
- "Interfejsy i klasy abstrakcyjne nie powinny zawierać przedrostków ani przyrostków":https://blog.nette.org/en/prefixes-and-suffixes-do-not-belong-in-interface-names jak `Abstract`, `Interface` czy `I`


Łamanie linii i nawiasy
=======================

Standard kodowania Nette odpowiada PSR-12 (albo PER Coding Style), ale w niektórych punktach go doprecyzowuje albo modyfikuje:

- Funkcje strzałkowe zapisuje się bez spacji przed nawiasem, czyli `fn($a) => $b`
- Między różnymi typami instrukcji importu `use` nie jest wymagana pusta linia
- Typ zwracany funkcji/metody i otwierający nawias klamrowy są zawsze w osobnych liniach:

```php
	public function find(
		string $dir,
		array $options,
	): array
	{
		// treść metody
	}
```

Otwierający nawias klamrowy w osobnej linii jest ważny dla wizualnego oddzielenia sygnatury funkcji/metody od ciała. Jeśli sygnatura jest w jednej linii, oddzielenie jest wyraźne (obrazek po lewej). Jeśli jest w wielu liniach, w PSR sygnatura i ciało zlewają się (środek), podczas gdy w standardzie Nette pozostają oddzielone (po prawej):

[* new-line-after.webp *]


Bloki dokumentacyjne (phpDoc)
=============================

Główna reguła: **nigdy nie duplikuj** żadnej informacji z sygnatury, jak typ parametru czy typ zwracany, bez wnoszenia wartości.

Blok dokumentacyjny definicji klasy:

- Zaczyna się opisem klasy
- Po nim pusta linia
- Po niej adnotacje `@property` (albo `@property-read`, `@property-write`), po jednej w linii. Składnia: adnotacja, spacja, typ, spacja, `$nazwa`
- Po nich adnotacje `@method`, po jednej w linii. Składnia: adnotacja, spacja, typ zwracany, spacja, `nazwa(typ $param, ...)`
- Adnotację `@author` pomija się. Autorstwo trzymane jest w historii kodu źródłowego
- Można użyć adnotacji `@internal` albo `@deprecated`

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

Blok dokumentacyjny właściwości zawierający tylko adnotację `@var` powinien być w jednej linii:

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

Blok dokumentacyjny definicji metody:

- Zaczyna się krótkim opisem metody
- Bez pustej linii
- Adnotacje `@param`, po jednej w linii
- Adnotacja `@return`
- Adnotacje `@throws`, po jednej w linii
- Można użyć adnotacji `@internal` albo `@deprecated`

Po każdej adnotacji następuje jedna spacja, z wyjątkiem `@param`, po której następują dwie spacje dla lepszej czytelności.

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


Funkcje i stałe globalne
========================

Funkcje i stałe globalne zapisuje się bez wiodącego odwrotnego ukośnika, czyli `count($arr)`, a nie `\count($arr)`. Dla funkcji, które PHP potrafi zoptymalizować, dodaj na początku pliku `use function`, żeby kompilator mógł przetłumaczyć je efektywniej. Należą do nich funkcje jak `count`, `strlen`, `is_array`, `is_string`, `is_scalar`, `sprintf` itd. Funkcje wypisuje się w jednej linii, żeby blok importów pozostał zwięzły:

```php
use Nette;
use function count, is_array, is_scalar, sprintf;
```

Sporadycznie importujemy też stałe, których znajomość wartości może pomóc kompilatorowi:

```php
use const PHP_OS_FAMILY;
```


Tabulatory zamiast spacji
=========================

Tabulatory mają nad spacjami kilka zalet:

- Rozmiar wcięcia da się dostosować w edytorach i w "sieci":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size
- Nie narzucają kodowi preferencji użytkownika co do rozmiaru wcięcia, przez co kod jest bardziej przenośny
- Da się je wpisać jednym naciśnięciem klawisza (wszędzie, nie tylko w edytorach zamieniających tabulatory na spacje)
- Wcięcia są ich przeznaczeniem
- Szanują potrzeby słabowidzących i niewidomych kolegów

Używając w naszych projektach tabulatorów, umożliwiamy dostosowanie szerokości, co większości ludzi może wydawać się zbędne, ale dla osób z wadami wzroku jest niezbędne.

Dla niewidomych programistów używających monitorów brajlowskich każda spacja reprezentuje jedną komórkę brajlowską. Jeśli więc domyślne wcięcie to 4 spacje, wcięcie 3. poziomu marnuje 12 cennych komórek brajlowskich, zanim kod w ogóle się zacznie. Na monitorze 40-komórkowym, najczęstszym przy laptopach, to ponad jedna czwarta dostępnych komórek zmarnowana bez dostarczenia jakiejkolwiek informacji.


{{priority: -1}}