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

Dokument ten opisuje zasady i zalecenia dotyczące rozwoju Nette. Musisz ich przestrzegać, gdy dodajesz kod do Nette. Najprostszym sposobem na to jest emulacja istniejącego kodu.
Chodzi o to, aby cały kod wyglądał tak, jakby został napisany przez jedną osobę .

Standard kodowania Nette jest zgodny z [rozszerzonym stylem kodowania PSR-12 |https://www.php-fig.org/psr/psr-12/] z dwoma głównymi wyjątkami: używa [tabulatorów zamiast spacji |#Tabs-Instead-of-Spaces] dla wcięć i [używa PascalCase dla stałych klas |https://blog.nette.org/pl/aby-mniej-krzyczec-w-kodzie].


Zasady ogólne .[#toc-general-rules]
===================================

- 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 zamknięcia musi być udokumentowany: `@mkdir($dir); // @ - directory may exist`
- Jeśli używany jest operator porównania typu weak typed (ie. `==`, `!=`, ...), intencja musi być udokumentowana: `// == to accept null`
- Możesz zapisać więcej wyjątków w jednym pliku `exceptions.php`
- Widoczność metod nie jest określona dla interfejsów, ponieważ są one zawsze publiczne.
- Każda właściwość, wartość zwracana i parametr muszą mieć określony typ. Natomiast dla stałych finalnych nigdy nie określamy typu, ponieważ jest on oczywisty.
- Do delimitacji ciągu znaków należy używać pojedynczych cudzysłowów, z wyjątkiem sytuacji, gdy sam literał zawiera apostrofy.


Konwencje nazewnicze .[#toc-naming-conventions]
===============================================

- Nie należy używać skrótów, chyba że pełna nazwa jest zbyt długa.
- Dla skrótów dwuliterowych należy używać dużych liter, dla dłuższych skrótów - pascal/camel.
- Użyj rzeczownika lub frazy rzeczownikowej dla nazwy klasy.
- Nazwy klas muszą zawierać nie tylko specyfikę (`Array`), ale także ogólność (`ArrayIterator`). Wyjątkiem są atrybuty PHP.
- "Stałe klasy i enum powinny używać PascalCaps":https://blog.nette.org/pl/aby-mniej-krzyczec-w-kodzie.
- "Interfejsy i klasy abstrakcyjne nie powinny zawierać przedrostków ani przyrostków":https://blog.nette.org/pl/przedrostki-i-przyrostki-nie-sa-czescia-nazw-interfejsow takich jak `Abstract`, `Interface` czy `I`.


Owijki i szelki .[#toc-wrapping-and-braces]
===========================================

Standard Kodowania Nette odpowiada PSR-12 (czyli stylowi kodowania PER), w niektórych punktach uzupełnia go lub modyfikuje:

- Funkcje strzałkowe zapisujemy bez spacji przed nawiasem, tzn. `fn($a) => $b`
- nie jest wymagany pusty wiersz pomiędzy różnymi typami `use` deklaracji importowych
- typ zwracany funkcji/metody i otwierający nawias klamrowy są zawsze w oddzielnych wierszach:

```php
	public function find(
		string $dir,
		array $options,
	): array
	{
		// tělo metody
	}
```

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

[* new-line-after.webp *]


Bloki dokumentacji (phpDoc) .[#toc-documentation-blocks-phpdoc]
===============================================================

Główna zasada: Nigdy nie powielaj żadnych informacji w podpisie, takich jak typ parametru lub typ powrotu, bez dodawania wartości.

Blok dokumentacji definicji klasy:

- Zaczyna się od opisu zajęć.
- Po czym następuje pusta linia.
- Adnotacje `@property` (lub `@property-read`, `@property-write`) następują jedna po drugiej. Składnia to: annotacja, spacja, typ, spacja, $name.
- Następujące adnotacje są `@method`, jedna po drugiej. Składnia to: adnotacja, spacja, typ zwrotny, spacja, nazwa($param typ, ...).
- Pomija się adnotację `@author`. Autorstwo jest zachowane w historii kodu źródłowego.
- Można stosować adnotacje `@internal` lub `@deprecated`.

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

Blok dokumentacji dla właściwości, która zawiera tylko adnotację `@var` powinien być pojedynczym wierszem:

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

Blok dokumentacji dla definicji metody:

- Zaczyna się od krótkiego opisu metody.
- Brak pustej linii.
- Adnotacja `@param` linia po linii.
- Annotacja `@return`.
- Adnotacja `@throws`, jeden po drugim.
- Można stosować adnotacje `@internal` lub `@deprecated`.

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

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


Tabulatory zamiast spacji .[#toc-tabs-instead-of-spaces]
========================================================

Tabulatory mają kilka zalet w stosunku do spacji:

- odstępy można regulować w edytorach i w "sieci:https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size "
- nie nakładają na kod preferencji użytkownika co do wielkości wcięcia, więc kod jest bardziej przenośny
- można je wpisać jednym naciśnięciem klawisza (wszędzie, nie tylko w edytorach zamieniających tabulatory na spacje)
- wcięcie jest ich celem
- szanują potrzeby kolegów niedowidzących i niewidomych

Stosując zakładki w naszych projektach, umożliwiamy regulację szerokości, co dla większości osób może wydawać się stratą, ale dla osób z wadami wzroku jest niezbędne.

Dla niewidomych programistów, którzy używają wyświetlaczy brajlowskich, każda spacja reprezentuje jedną komórkę brajlowską. Jeśli więc domyślne wcięcie to 4 spacje, wcięcie na poziomie 3 marnuje 12 cennych komórek brajla, zanim jeszcze rozpocznie się kod.
Na 40-komorowym wyświetlaczu, który jest najczęściej stosowany w laptopach, to ponad jedna czwarta dostępnych komórek marnuje się bez żadnych informacji.


{{priority: -1}}