Kódovací standard

Tento dokument popisuje pravidla a doporučení pro vývoj Nette. Při přispívání kódu do Nette je musíte dodržovat. Nejjednodušší způsob, jak to udělat, je napodobit existující kód. Jde o to, aby veškerý kód vypadal, jako by ho napsal jeden člověk .

Nette Coding Standard odpovídá PSR-12 Extended Coding Style se dvěma hlavními výjimkami: pro odsazení používá tabulátory místo mezer a pro konstanty tříd používá PascalCase.

Obecná pravidla

• Každý soubor PHP musí obsahovat declare(strict_types=1)
• Dva prázdné řádky se používají k oddělení metod pro lepší čitelnost.
• Důvod použití shut-up operátoru musí být zdokumentován: @mkdir($dir); // @ - adresář může existovat.
• Pokud je použit slabě typizovaný operátor porovnání (tj. ==, !=, …), musí být zdokumentován záměr: // == přijmout null
• Do jednoho souboru exceptions.php můžete zapsat více výjimek.
• U rozhraní se nespecifikuje viditelnost metod, protože jsou vždy veřejné.
• Každá property, návratová hodnota a parametr musí mít uvedený typ. Naopak u finálních konstant typ nikdy neuvádíme, protože je zjevný.
• K ohraničení řetězce by se měly používat jednoduché uvozovky, s výjimkou případů, kdy samotný literál obsahuje apostrofy.

Pojmenovací konvence

• Nepoužívejte zkratky, pokud není celý název příliš dlouhý.
• U dvoupísmenných zkratek používejte velká písmena, u delších zkratek pascal/camel.
• Pro název třídy používejte podstatné jméno nebo slovní spojení.
• Názvy tříd musí obsahovat nejen specifičnost (Array), ale také obecnost (ArrayIterator). Výjimkou jsou atributy jazyka PHP.
• Konstanty tříd a enumy by měly používat PascalCaps.
• Rozhraní a abstraktní třídy by neměly obsahovat předpony nebo přípony jako Abstract, Interface nebo I.

Wrapping and Braces

Nette Coding Standard odpovídá PSR-12 (resp. PER Coding Style), v některých bodech jej doplňuje nebo upravuje:

• arrow funkce se píší bez mezery před závorkou, tj. fn($a) => $b
• nevyžaduje se prázdný řádek mezi různými typy use import statements
• návratový typ funkce/metody a úvodní složená závorka jsou vždy na samostatných řádcích:

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

Úvodní složená závorka na samostatném řádku je důležitá pro vizuální oddělení signatury funkce/metody od těla. Pokud je signatura na jednom řádku, je oddělení zřetelné (obrázek vlevo), pokud je na více řádcích, v PSR signatury a těla splývají (uprostřed), zatímco v Nette standardu jsou nadále oddělené (vpravo):

Bloky dokumentace (phpDoc)

Hlavní pravidlo: Nikdy neduplikujte žádné informace v signatuře, jako je typ parametru nebo návratový typ, bez přidané hodnoty.

Dokumentační blok pro definici třídy:

• Začíná popisem třídy.
• Následuje prázdný řádek.
• Následují anotace @property (nebo @property-read, @property-write), jedna po druhé. Syntaxe je: anotace, mezera, typ, mezera, $jméno.
• Následují anotace @method, jedna po druhé. Syntaxe je: anotace, mezera, návratový typ, mezera, jméno(typ $param, …).
• Anotace @author se vynechává. Autorství se uchovává v historii zdrojového kódu.
• Lze použít anotace @internal nebo @deprecated.

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

Dokumentační blok pro vlastnost, který obsahuje pouze anotaci @var, by měl být jednořádkový:

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

Dokumentační blok pro definici metody:

• Začíná krátkým popisem metody.
• Žádný prázdný řádek.
• Anotace @param po jednotlivých řádcích.
• Anotace @return.
• Anotace @throws, jedna po druhé.
• Lze použít anotace @internal nebo @deprecated.

Za každou anotací následuje jedna mezera, s výjimkou @param, za kterou pro lepší čitelnost následují dvě mezery.

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

Tabulátory místo mezer

Tabulátory mají oproti mezerám několik výhod:

• velikost odstupu lze v editorech a na webu přizpůsobit
• nevnucují kódu uživatelovu preferenci velikosti odsazení, takže kód je lépe přenositelný
• lze je napsat jedním stiskem klávesy (kdekoli, nejen v editorech, které mění tabulátory na mezery)
• odsazování je jejich smyslem
• respektují potřeby zrakově postižených a nevidomých kolegů

Používáním tabulátorů v našich projektech umožňujeme přizpůsobení šířky, které se může většině lidí zdát jako zbytečnost, ale pro lidi se zrakovým postižením je nezbytné.

Pro nevidomé programátory, kteří používají braillské displeje, představuje každá mezera jednu braillskou buňkou. Pokud je tedy výchozí odsazení 4 mezery, odsazení 3. úrovně plýtvá 12 cennými braillskými buňkami ještě před začátkem kódu. Na 40buňkovém displeji, který se u notebooků používá nejčastěji, je to více než čtvrtina dostupných buněk, které jsou promrhány bez jakékoliv informace.