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 plně dodržuje PSR-12 Extended Coding Style se dvěma 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.
  • Rozhraní nespecifikují viditelnost metod, protože jsou vždy veřejné.
  • Každá vlastnost, metoda a parametr musí mít dokumentovaný typ. Buď nativně, nebo pomocí anotace.
  • Pole se musí zapisovat krátkým zápisem.
  • K ohraničení řetězce by se měla používat jednoduchá uvozovka, s výjimkou případů, kdy samotný literál obsahuje apostrofy.

Pojmenovací konvence

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.