Стандарт за кодиране
********************

.[perex]
Този документ описва правилата и препоръките за разработка на Nette. При допринасяне на код към Nette трябва да ги спазвате. Най-лесният начин да го направите е да имитирате съществуващия код. Целта е целият код да изглежда така, сякаш е написан от един човек.

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


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

- Всеки PHP файл трябва да съдържа `declare(strict_types=1)`
- Два празни реда се използват за разделяне на методи за по-добра четливост.
- Причината за използване на shut-up оператора трябва да бъде документирана: `@mkdir($dir); // @ - директорията може да съществува`.
- Ако се използва оператор за сравнение със слабо типизиране (т.е. `==`, `!=`, ...), намерението трябва да бъде документирано: `// == приема null`
- В един файл `exceptions.php` можете да запишете няколко изключения.
- При интерфейсите не се специфицира видимостта на методите, тъй като те винаги са публични.
- Всяко свойство, върната стойност и параметър трябва да имат посочен тип. Обратно, при `final` константи никога не посочваме тип, тъй като той е очевиден.
- За ограждане на низ трябва да се използват единични кавички, с изключение на случаите, когато самият литерал съдържа апострофи.


Конвенции за именуване
======================

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


Обвиване и скоби
================

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

- arrow функциите се пишат без интервал преди скобата, т.е. `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}}