Nette Documentation Preview

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

.[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}}

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

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

Стандартът за кодиране на Nette отговаря на PSR-12 Extended Coding Style, с две основни изключения: за отстъп използва табулатори вместо интервали и за константи на класове използва PascalCase.

Общи правила

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

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

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

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

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

Табулатори вместо интервали

Табулаторите имат няколко предимства пред интервалите:

  • размерът на отстъпа може да се персонализира в редакторите и в уеб
  • не налагат на кода предпочитанията на потребителя за размера на отстъпа, така че кодът е по-преносим
  • могат да се напишат с едно натискане на клавиш (навсякъде, не само в редактори, които превръщат табулаторите в интервали)
  • отстъпването е тяхната цел
  • уважават нуждите на колегите със зрителни увреждания и незрящите

Чрез използването на табулатори в нашите проекти позволяваме персонализиране на ширината, което може да изглежда като излишно за повечето хора, но за хората със зрителни увреждания е необходимо.

За незрящите програмисти, които използват брайлови дисплеи, всеки интервал представлява една брайлова клетка. Така че, ако отстъпът по подразбиране е 4 интервала, отстъпът от 3-то ниво губи 12 ценни брайлови клетки още преди началото на кода. На 40-клетъчен дисплей, който се използва най-често при лаптопи, това е повече от една четвърт от наличните клетки, които са пропилени без никаква информация.