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

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

Стандарт кодирования Nette соответствует [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] с двумя основными исключениями: он использует [#tabs вместо пробелов] для отступов и использует [PascalCase для констант классов|https://blog.nette.org/ru/ctoby-men-se-kricat-v-kode].


Общие правила .[#toc-general-rules]
===================================

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


Соглашения об именовании .[#toc-naming-conventions]
===================================================

- Не используйте аббревиатуры, если только полное имя не слишком длинное.
- Используйте прописные буквы для двухбуквенных аббревиатур, паскаль/камель для более длинных аббревиатур.
- Используйте существительное или словосочетание для названия класса.
- Имена классов должны содержать не только конкретику (`Array`), но и обобщение (`ArrayIterator`). Исключением являются атрибуты PHP.
- "Константы классов и перечисления должны использовать PascalCaps":https://blog.nette.org/ru/ctoby-men-se-kricat-v-kode.
- "Интерфейсы и абстрактные классы не должны содержать префиксы или суффиксы":https://blog.nette.org/ru/prefiksy-i-suffiksy-ne-dolzny-prisutstvovat-v-imenah-interfejsov, такие как `Abstract`, `Interface` или `I`.


Обертывание и брекеты .[#toc-wrapping-and-braces]
=================================================

Nette Coding Standard соответствует 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) .[#toc-documentation-blocks-phpdoc]
===============================================================

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

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

- Начинается с описания класса.
- Далее следует пустая строка.
- Далее следуют аннотации `@property` (или `@property-read`, `@property-write`), одна за другой. Синтаксис следующий: аннотация, пробел, тип, пробел, $name.
- Далее следуют аннотации `@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
```


Табуляция вместо пробелов .[#toc-tabs-instead-of-spaces]
========================================================

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

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

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

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


{{priority: -1}}