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

.[perex]
Ten dokument opisuje zasady i zalecenia dotyczące rozwoju Nette. Przy współtworzeniu kodu do Nette musisz ich przestrzegać. Najprostszym sposobem, aby to zrobić, jest naśladowanie istniejącego kodu. Chodzi o to, aby cały kod wyglądał, 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 [#tabulatory zamiast spacji] i dla [stałych klas używa PascalCase|https://blog.nette.org/pl/for-less-screaming-in-the-code].


Ogólne zasady
=============

- Każdy plik PHP musi zawierać `declare(strict_types=1)`
- Dwie puste linie są używane do oddzielenia metod dla lepszej czytelności.
- Powód użycia operatora wyciszenia musi być udokumentowany: `@mkdir($dir); // @ - katalog może istnieć`.
- Jeśli używany jest operator porównania słabo typizowanego (tj. `==`, `!=`, ...), musi być udokumentowany zamiar: `// == akceptuj null`
- Do jednego pliku `exceptions.php` możesz zapisać wiele wyjątków.
- W interfejsach nie określa się widoczności metod, ponieważ są zawsze publiczne.
- Każda właściwość, wartość zwracana i parametr musi mieć podany typ. Natomiast przy stałych finalnych typu nigdy nie podajemy, ponieważ jest oczywisty.
- Do ograniczenia ciągu znaków należy używać pojedynczych cudzysłowów, z wyjątkiem przypadków, gdy sam literał zawiera apostrofy.


Konwencje nazewnictwa
=====================

- Nie używaj skrótów, chyba że pełna nazwa jest zbyt długa.
- W przypadku dwuliterowych skrótów używaj wielkich liter, w przypadku dłuższych skrótów pascal/camel.
- Dla nazwy klasy używaj rzeczownika lub wyrażenia rzeczownikowego.
- Nazwy klas muszą zawierać nie tylko specyficzność (`Array`), ale także ogólność (`ArrayIterator`). Wyjątkiem są atrybuty języka PHP.
- "Stałe klas i enumy powinny używać PascalCaps":https://blog.nette.org/pl/for-less-screaming-in-the-code.
- "Interfejsy i klasy abstrakcyjne nie powinny zawierać prefiksów ani sufiksów":https://blog.nette.org/pl/prefixes-and-suffixes-do-not-belong-in-interface-names jak `Abstract`, `Interface` lub `I`.


Zawijanie i nawiasy klamrowe
============================

Standard kodowania Nette odpowiada PSR-12 (resp. PER Coding Style), w niektórych punktach go uzupełnia lub modyfikuje:

- funkcje strzałkowe pisze się bez spacji przed nawiasem, tj. `fn($a) => $b`
- nie wymaga się pustej linii między różnymi typami instrukcji importu `use`
- typ zwracany funkcji/metody i otwierający nawias klamrowy są zawsze na osobnych liniach:

```php
	public function find(
		string $dir,
		array $options,
	): array
	{
		// ciało metody
	}
```

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

[* new-line-after.webp *]


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

Główna zasada: Nigdy nie duplikuj żadnych informacji w sygnaturze, takich jak typ parametru lub typ zwracany, bez dodanej wartości.

Blok dokumentacyjny dla definicji klasy:

- Zaczyna się opisem klasy.
- Następuje pusta linia.
- Następują adnotacje `@property` (lub `@property-read`, `@property-write`), jedna po drugiej. Składnia to: adnotacja, spacja, typ, spacja, $nazwa.
- Następują adnotacje `@method`, jedna po drugiej. Składnia to: adnotacja, spacja, typ zwracany, spacja, nazwa(typ $param, ...).
- Adnotacja `@author` jest pomijana. Autorstwo jest przechowywane w historii kodu źródłowego.
- Można użyć adnotacji `@internal` lub `@deprecated`.

```php
/**
 * Część wiadomości MIME.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */
```

Blok dokumentacyjny dla właściwości, który zawiera tylko adnotację `@var`, powinien być jednoliniowy:

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

Blok dokumentacyjny dla definicji metody:

- Zaczyna się krótkim opisem metody.
- Brak pustej linii.
- Adnotacje `@param` w osobnych liniach.
- Adnotacja `@return`.
- Adnotacje `@throws`, jedna po drugiej.
- Można użyć adnotacji `@internal` lub `@deprecated`.

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

```php
/**
 * Znajduje plik w katalogu.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array
```


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

Tabulatory mają w porównaniu ze spacjami kilka zalet:

- rozmiar wcięcia można dostosować w edytorach i na "webie":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size
- nie narzucają kodowi preferencji użytkownika co do rozmiaru wcięcia, dzięki czemu kod jest lepiej przenośny
- można je napisać jednym naciśnięciem klawisza (wszędzie, nie tylko w edytorach, które zamieniają tabulatory na spacje)
- wcięcie jest ich celem
- szanują potrzeby kolegów z wadami wzroku i niewidomych

Używając tabulatorów w naszych projektach, 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, którzy używają monitorów brajlowskich, każda spacja stanowi 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 jeszcze przed rozpoczęciem kodu. Na 40-komórkowym monitorze, który jest najczęściej używany w laptopach, to ponad ćwierć dostępnych komórek, które są marnowane bez żadnej informacji.


{{priority: -1}}