Стандарт за кодиране

Този документ описва правилата и препоръките за разработка на Nette. При допринасяне на код към Nette трябва да ги спазвате. Най-лесният начин да го направите е да имитирате съществуващия код. Целта е целият код да изглежда така, сякаш е написан от един човек.

Стандартът за кодиране на Nette отговаря на PSR-12 Extended Coding Style, с две основни изключения: за отстъп използва табулатори вместо интервали и за константи на класове използва PascalCase.

Общи правила

• Всеки PHP файл трябва да съдържа declare(strict_types=1)
• Два празни реда се използват за разделяне на методи за по-добра четливост.
• Причината за използване на shut-up оператора трябва да бъде документирана: @mkdir($dir); // @ - директорията може да съществува.
• Ако се използва оператор за сравнение със слабо типизиране (т.е. ==, !=, …), намерението трябва да бъде документирано: // == приема null
• В един файл exceptions.php можете да запишете няколко изключения.
• При интерфейсите не се специфицира видимостта на методите, тъй като те винаги са публични.
• Всяко свойство, върната стойност и параметър трябва да имат посочен тип. Обратно, при финалните константи никога не посочваме тип, тъй като той е очевиден.
• За ограждане на низ трябва да се използват единични кавички, с изключение на случаите, когато самият литерал съдържа апострофи.

Конвенции за именуване

• Не използвайте съкращения, освен ако цялото име не е твърде дълго.
• При двубуквени съкращения използвайте главни букви, при по-дълги съкращения pascal/camel.
• За име на клас използвайте съществително име или словосъчетание.
• Имената на класовете трябва да съдържат не само спецификата (Array), но и общността (ArrayIterator). Изключение са атрибутите на езика PHP.
• Константите на класове и енумите трябва да използват PascalCaps.
• Интерфейсите и абстрактните класове не трябва да съдържат префикси или суфикси като Abstract, Interface или I.

Обвиване и скоби

Стандартът за кодиране на Nette отговаря на PSR-12 (респ. PER Coding Style), в някои точки го допълва или променя:

• arrow функциите се пишат без интервал преди скобата, т.е. fn($a) => $b
• не се изисква празен ред между различните типове use import statements
• типът на връщаната стойност на функция/метод и началната фигурна скоба винаги са на отделни редове:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// тяло на метода
	}

Началната фигурна скоба на отделен ред е важна за визуалното разделяне на сигнатурата на функцията/метода от тялото. Ако сигнатурата е на един ред, разделянето е ясно (изображение вляво), ако е на няколко реда, в PSR сигнатурата и тялото се сливат (в средата), докато в стандарта на Nette те продължават да бъдат разделени (вдясно):

Документационни блокове (phpDoc)

Основно правило: Никога не дублирайте никаква информация в сигнатурата, като тип на параметър или тип на връщаната стойност, без добавена стойност.

Документационен блок за дефиниция на клас:

• Започва с описание на класа.
• Следва празен ред.
• Следват анотации @property (или @property-read, @property-write), една след друга. Синтаксисът е: анотация, интервал, тип, интервал, $име.
• Следват анотации @method, една след друга. Синтаксисът е: анотация, интервал, тип на връщаната стойност, интервал, име(тип $param, …).
• Анотацията @author се пропуска. Авторството се съхранява в историята на изходния код.
• Могат да се използват анотации @internal или @deprecated.

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

Документационен блок за свойство, който съдържа само анотация @var, трябва да бъде едноредов:

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

Документационен блок за дефиниция на метод:

• Започва с кратко описание на метода.
• Без празен ред.
• Анотации @param на отделни редове.
• Анотация @return.
• Анотации @throws, една след друга.
• Могат да се използват анотации @internal или @deprecated.

След всяка анотация следва един интервал, с изключение на @param, след която за по-добра четливост следват два интервала.

/**
 * Намира файл в директория.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Табулатори вместо интервали

Табулаторите имат няколко предимства пред интервалите:

• размерът на отстъпа може да се персонализира в редакторите и в уеб
• не налагат на кода предпочитанията на потребителя за размера на отстъпа, така че кодът е по-преносим
• могат да се напишат с едно натискане на клавиш (навсякъде, не само в редактори, които превръщат табулаторите в интервали)
• отстъпването е тяхната цел
• уважават нуждите на колегите със зрителни увреждания и незрящите

Чрез използването на табулатори в нашите проекти позволяваме персонализиране на ширината, което може да изглежда като излишно за повечето хора, но за хората със зрителни увреждания е необходимо.

За незрящите програмисти, които използват брайлови дисплеи, всеки интервал представлява една брайлова клетка. Така че, ако отстъпът по подразбиране е 4 интервала, отстъпът от 3-то ниво губи 12 ценни брайлови клетки още преди началото на кода. На 40-клетъчен дисплей, който се използва най-често при лаптопи, това е повече от една четвърт от наличните клетки, които са пропилени без никаква информация.