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

.[perex]
Цей документ описує правила та рекомендації для розробки Nette. При внесенні коду до Nette ви повинні їх дотримуватися. Найпростіший спосіб зробити це – наслідувати існуючий код. Мета полягає в тому, щоб весь код виглядав так, ніби його написала одна людина.

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


Загальні правила
================

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


Угоди про іменування
====================

- Не використовуйте скорочення, якщо повна назва не надто довга.
- Для дволітерних скорочень використовуйте великі літери, для довших скорочень – Pascal/camelCase.
- Для назви класу використовуйте іменник або словосполучення.
- Назви класів повинні містити не лише специфічність (`Array`), але й загальність (`ArrayIterator`). Винятком є атрибути мови PHP.
- "Константи класів та enum-и повинні використовувати PascalCase":https://blog.nette.org/uk/for-less-screaming-in-the-code.
- "Інтерфейси та абстрактні класи не повинні містити префіксів або суфіксів":https://blog.nette.org/uk/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
/**
 * Знаходить файл у каталозі.
 * @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}}