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

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

Стандарт кодирования Nette соответствует [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] с двумя основными исключениями: для отступов он использует [#Табуляции вместо пробелов] и для [констант классов использует PascalCase|https://blog.nette.org/ru/for-less-screaming-in-the-code].


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

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


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

- Не используйте сокращения, если полное имя не слишком длинное.
- Для двухбуквенных аббревиатур используйте заглавные буквы, для более длинных аббревиатур — PascalCase/camelCase.
- Для имени класса используйте существительное или словосочетание.
- Имена классов должны содержать не только специфичность (`Array`), но и общность (`ArrayIterator`). Исключением являются атрибуты языка PHP.
- "Константы классов и перечисления должны использовать PascalCaps":https://blog.nette.org/ru/for-less-screaming-in-the-code.
- "Интерфейсы и абстрактные классы не должны содержать префиксы или суффиксы":https://blog.nette.org/ru/prefixes-and-suffixes-do-not-belong-in-interface-names, такие как `Abstract`, `Interface` или `I`.


Перенос строк и скобки
======================

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

- стрелочные функции пишутся без пробела перед скобкой, т.е. `fn($a) => $b`
- не требуется пустая строка между различными типами импортов `use`
- возвращаемый тип функции/метода и открывающая фигурная скобка всегда находятся на отдельных строках:

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

Открывающая фигурная скобка на отдельной строке важна для визуального разделения сигнатуры функции/метода от тела. Если сигнатура находится на одной строке, разделение очевидно (рисунок слева), если на нескольких строках, в PSR сигнатуры и тела сливаются (посередине), в то время как в стандарте Nette они остаются разделенными (справа):

[* new-line-after.webp *]


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

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

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

- Начинается с описания класса.
- Следует пустая строка.
- Следуют аннотации `@property` (или `@property-read`, `@property-write`), одна за другой. Синтаксис: аннотация, пробел, тип, пробел, $имя.
- Следуют аннотации `@method`, одна за другой. Синтаксис: аннотация, пробел, возвращаемый тип, пробел, имя(тип $param, ...).
- Аннотация `@author` опускается. Авторство сохраняется в истории исходного кода.
- Можно использовать аннотации `@internal` или `@deprecated`.

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

Блок документации для свойства, содержащий только аннотацию `@var`, должен быть однострочным:

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

Блок документации для определения метода:

- Начинается с краткого описания метода.
- Нет пустой строки.
- Аннотации `@param` по отдельным строкам.
- Аннотация `@return`.
- Аннотации `@throws`, одна за другой.
- Можно использовать аннотации `@internal` или `@deprecated`.

За каждой аннотацией следует один пробел, за исключением `@param`, за которой для лучшей читаемости следуют два пробела.

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


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

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

- размер отступа можно настроить в редакторах и на "веб-сайте":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size
- они не навязывают коду предпочтение пользователя в размере отступа, поэтому код лучше переносим
- их можно написать одним нажатием клавиши (где угодно, не только в редакторах, которые заменяют табуляции на пробелы)
- отступы — это их смысл
- они уважают потребности коллег с нарушениями зрения и незрячих

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

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


{{priority: -1}}