/
coding-standard.texy
129 lines (94 loc) · 9.66 KB
/
coding-standard.texy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
Стандарт кодирования
********************
В этом документе описаны правила и рекомендации по разработке Nette. Предоставляя код для Nette, вы должны следовать им. Самый простой способ сделать это — имитировать существующий код.
Идея заключается в том, чтобы весь код выглядел так, как будто его написал один человек.
Стандарт кодирования Nette соответствует [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] с двумя основными исключениями: он использует [#tabs вместо пробелов] для отступов и использует [PascalCase для констант классов|https://blog.nette.org/ru/ctoby-men-se-kricat-v-kode].
Общие правила .[#toc-general-rules]
===================================
- Каждый файл PHP должен содержать `declare(strict_types=1)`
- Две пустые строки используются для разделения методов для лучшей читабельности.
- Причина использования оператора закрытия должна быть задокументирована: `@mkdir($dir); // @ - directory may exist`
- Если используется слабо типизированный оператор сравнения (т.е. `==`, `!=`, ...), то намерение должно быть задокументировано: `// == to accept null`
- Вы можете записать больше исключений в один файл `exceptions.php`
- Видимость методов не указывается для интерфейсов, поскольку они всегда являются общедоступными.
- Для каждого свойства, возвращаемого значения и параметра должен быть указан тип. С другой стороны, для конечных констант мы никогда не указываем тип, потому что он очевиден.
- Для разделения строки следует использовать одинарные кавычки, за исключением случаев, когда сам литерал содержит апострофы.
Соглашения об именовании .[#toc-naming-conventions]
===================================================
- Не используйте аббревиатуры, если только полное имя не слишком длинное.
- Используйте прописные буквы для двухбуквенных аббревиатур, паскаль/камель для более длинных аббревиатур.
- Используйте существительное или словосочетание для названия класса.
- Имена классов должны содержать не только конкретику (`Array`), но и обобщение (`ArrayIterator`). Исключением являются атрибуты PHP.
- "Константы классов и перечисления должны использовать PascalCaps":https://blog.nette.org/ru/ctoby-men-se-kricat-v-kode.
- "Интерфейсы и абстрактные классы не должны содержать префиксы или суффиксы":https://blog.nette.org/ru/prefiksy-i-suffiksy-ne-dolzny-prisutstvovat-v-imenah-interfejsov, такие как `Abstract`, `Interface` или `I`.
Обертывание и брекеты .[#toc-wrapping-and-braces]
=================================================
Nette Coding Standard соответствует 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`), одна за другой. Синтаксис следующий: аннотация, пробел, тип, пробел, $name.
- Далее следуют аннотации `@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
/**
* 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}}