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 z dwoma głównymi wyjątkami: używa tabulatorów zamiast spacji dla wcięć i używa PascalCase dla stałych klas.

Zasady ogólne

• 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

• 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.
• Interfejsy i klasy abstrakcyjne nie powinny zawierać przedrostków ani przyrostków takich jak Abstract, Interface czy I.

Owijki i szelki

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:

	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):

Bloki dokumentacji (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.

/**
 * 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:

/** @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.

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

Tabulatory zamiast spacji

Tabulatory mają kilka zalet w stosunku do spacji:

• odstępy można regulować w edytorach i w “sieci:https://developer.mozilla.org/…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.