Стандарт кодирования

Этот документ описывает правила и рекомендации для разработки Nette. При внесении вклада в код Nette вы должны их соблюдать. Самый простой способ сделать это — подражать существующему коду. Цель в том, чтобы весь код выглядел так, как будто его написал один человек.

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

Общие правила

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

Соглашения об именовании

• Не используйте сокращения, если полное имя не слишком длинное.
• Для двухбуквенных аббревиатур используйте заглавные буквы, для более длинных аббревиатур — PascalCase/camelCase.
• Для имени класса используйте существительное или словосочетание.
• Имена классов должны содержать не только специфичность (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), одна за другой. Синтаксис: аннотация, пробел, тип, пробел, $имя.
• Следуют аннотации @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, за которой для лучшей читаемости следуют два пробела.

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

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

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

• размер отступа можно настроить в редакторах и на веб-сайте
• они не навязывают коду предпочтение пользователя в размере отступа, поэтому код лучше переносим
• их можно написать одним нажатием клавиши (где угодно, не только в редакторах, которые заменяют табуляции на пробелы)
• отступы — это их смысл
• они уважают потребности коллег с нарушениями зрения и незрячих

Используя табуляции в наших проектах, мы позволяем настраивать ширину, что большинству людей может показаться излишеством, но для людей с нарушениями зрения это необходимо.

Для незрячих программистов, использующих дисплеи Брайля, каждый пробел представляет собой одну ячейку Брайля. Если, таким образом, отступ по умолчанию составляет 4 пробела, отступ 3-го уровня тратит 12 ценных ячеек Брайля еще до начала кода. На 40-ячеечном дисплее, который чаще всего используется в ноутбуках, это более четверти доступных ячеек, которые тратятся без какой-либо информации.