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

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

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

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

• Кожен PHP-файл повинен містити declare(strict_types=1)
• Два порожніх рядки використовуються для розділення методів для кращої читабельності.
• Причина використання оператора shut-up повинна бути задокументована: @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-осередковому дисплеї, який найчастіше використовується на ноутбуках, це понад чверть доступних осередків, витрачених даремно без будь-якої інформації.