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

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

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

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

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

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

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

Обертывание и брекеты

Nette Coding Standard соответствует 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), одна за другой. Синтаксис следующий: аннотация, пробел, тип, пробел, $name.
• Далее следуют аннотации @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 пробела, отступ третьего уровня отнимает 12 ячеек Брайля перед началом кода. На 40-ячеечном дисплее, который чаще всего используется на ноутбуках, это более четверти доступных ячеек, потраченных впустую без какой-либо информации.