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

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

Стандартът за кодиране на Nette следва [разширения стил на кодиране PSR-12 |https://www.php-fig.org/psr/psr-12/] с две основни изключения: използва [табулации вместо интервали |#tabs вместо пробелов] за отстъпите и използва [PascalCase за константите на класовете |https://blog.nette.org/bg/za-po-malko-kresene-v-koda].


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

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


Конвенции за именуване .[#toc-naming-conventions]
=================================================

- Не използвайте съкращения, освен ако пълното име не е твърде дълго.
- Използвайте главни букви за двубуквени съкращения, а паскал/камела за по-дълги съкращения.
- Използвайте съществително име или съществително словосъчетание за името на класа.
- Имената на класовете трябва да съдържат не само конкретност (`Array`), но и обобщеност (`ArrayIterator`). PHP атрибутите са изключение.
- "Константите на класовете и енумите трябва да използват PascalCaps":https://blog.nette.org/bg/za-po-malko-kresene-v-koda.
- "Интерфейсите и абстрактните класове не трябва да съдържат префикси или суфикси":https://blog.nette.org/bg/prefiksite-i-sufiksite-ne-prinadlezat-na-imenata-na-interfejsite като `Abstract`, `Interface` или `I`.


Обвивки и скоби .[#toc-wrapping-and-braces]
===========================================

Стандартът за кодиране на 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) .[#toc-documentation-blocks-phpdoc]
====================================================================

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

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

- Започва с описание на класа.
- След това се поставя празен ред.
- След това се добавят една след друга анотациите `@property` (или `@property-read`, `@property-write`). Синтаксисът е: annotation, space, type, space, $name.
- След това се добавят една след друга анотациите `@method`. Синтаксисът е следният: annotation, space, return type, space, name(type $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}}