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

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

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

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

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

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

• Не використовуйте скорочення, якщо повна назва не надто довга.
• Для дволітерних скорочень використовуйте великі літери, для довших скорочень – Pascal/camelCase.
• Для назви класу використовуйте іменник або словосполучення.
• Назви класів повинні містити не лише специфічність (Array), але й загальність (ArrayIterator). Винятком є атрибути мови PHP.
• Константи класів та enum-и повинні використовувати PascalCase.
• Інтерфейси та абстрактні класи не повинні містити префіксів або суфіксів як Abstract, Interface або I.

Перенесення та фігурні дужки

Стандарт кодування Nette відповідає 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), одна за одною. Синтаксис: анотація, пробіл, тип, пробіл, $ім'я.
• Слідують анотації @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, за якою для кращої читабельності слідують два пробіли.

/**
 * Знаходить файл у каталозі.
 * @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-комірковому дисплеї, який найчастіше використовується для ноутбуків, це більше чверті доступних комірок, які марнуються без будь-якої інформації.