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

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

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

Общи правила

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

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

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

Обвивки и скоби

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

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

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

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

Блокове за документация (phpDoc)

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

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

• Започва с описание на класа.
• След това се поставя празен ред.
• След това се добавят една след друга анотациите @property (или @property-read, @property-write). Синтаксисът е: annotation, space, type, space, $name.
• След това се добавят една след друга анотациите @method. Синтаксисът е следният: annotation, space, return type, space, name(type $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, последван от два интервала за по-добра четливост.

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

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

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

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

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

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