Standard kodowania

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

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.
• Interfejsy i klasy abstrakcyjne nie powinny zawierać prefiksów ani sufiksów 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:

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

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.

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

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

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