Общее
1. Файлы с исходным кодом
1.1. Правила именования
Имя файла должно быть в нижнем регистре.
Имя файла может содержать логические группы. Группы разделяются точкой (символ .).
Если имя файла состоит из нескольких слов, то они разделяются дефисом (символ -).
1.2. Кодировка
Файлы с исходным кодом должны использовать кодировку UTF-8.
1.3. Используемые специальные символы
1.3.1. Пробельные
В качестве пробельного символа должен использоваться только символ пробела (0x20). Не должно быть использования других пробельных символов. Исключением является только символ завершения строки.
Таким образом, в качестве символа для определения отступов также используемся символ пробела. Использование символа табуляции недопустимо. Величина отступов и их оформление указаны в п.3.2.
1.3.2. Использование управляющих последовательностей символов
Если управляющая последовательность имеет своё символьное представление, то следует использовать его, нежели использовать её числовое выражение:
1.3.3. Символы вне таблицы ASCII символов
Использовать управляющую последовательность unicode для представления символа, если он является непечатаемым символом. При использовании таких символов обозначать их через константу с однозначным и понятным названием, которое раскрывает смысл используемого символа.
2. Структура каталогов
Проект должен придерживаться следующей структуры:
Пример структуры:
3. Форматирование
3.1. [Автоматизировано: max-len] Длина строк
Длина строк не должна превышать 120 символов. Строка не может быть чуть-чуть длиннее указанной границы. Либо строка соответствует установленному лимиту, либо нет. Если строка превышает ограничение, нужно переносить её части в соответствии с правилами переноса выражений, указанными в разделе 3.5. Перенос выражений.
Исключения составляют только следующие случаи:
строки, которые не разорвать, например, длинный URL в JSDoc. С похожей ситуацией
можно столкнуться в json-файлах, которые также встречаются в проектах на javascript.
3.2. [Автоматизировано: no-multiple-empty-lines] Пробельные места
Файл должен завершаться строкой с содержимым, не должно быть пустой строки в конце файла.
4. Политики
4.1. Код не соответствует правилам руководства
a. Если вносятся существенные изменения в файл, который не соответствует принятым в настоящем руководстве правилам, то следует предварительно выполнить форматирование файла в соответствии с правилами.
b. Если вносятся незначительные изменения в файл, то привести к формату правил только тот участок кода, в который вносятся изменения.
c. Новый код должен соответствовать правилам руководства.
4.2. Сгенерированный код
Сгенерированный код, который используется в проекте, может не соответствовать правилам руководства. Однако имена идентификаторов, которые используются в проекте должны соответствовать правилам настоящего руководства. Это соответствие должно быть обеспечено либо на уровне генерируемого кода, либо на уровне приложения за счёт дополнительных преобразований.
4.3. Автоматизированные инспекции кода и фиксация изменений
Необходимо уделять внимание автоматизированным инспекция в IDE и инспекциям инструмента проверки кода eslint
/ tslint
. Недопустимо выполнять фиксацию кода в репозитории, если он не проходит проверку на соответствие принятому стандарту написания кода.
5. Правила именования
5.1. [Не автоматизировано] Общие правила для всех идентификаторов
a. Используются только буквы латинского алфавита [a-zA-Z]
, цифры [0-9]
.
b. Необходимо давать максимально говорящие, понятные имена. Делать выбор в пользу более длинного названия, нежели в пользу менее понятного. В то же время необходимо, чтобы названия по возможности состояли из наименьшего количества слов (в идеале из одного), и их смысл был ясен, исходя из контекста. Идеальное название - короткое, лаконичное и в то же время полностью раскрывающее назначение.
c. Не использовать аббревиатуры, которые не являются общепринятыми.
d. Не использовать сокращений, которые не являются общепринятыми.
e. Использовать слова count
и number of
для названия переменных, в которых содержится некоторое количество. В случаях, когда может быть двусмысленность при использовании count
, отдавать предпочтение варианту с number of
h. Не использовать более двух идущих подряд существительных. Добавлять в этом случае какие-то предлоги-связки, например of
.
i. Не использовать в качестве названий слова являющиеся служебными для языка.
j. Имена переменных должны состоять из слов, имеющих определенное смысловое значение в английском языке. Не допускается использовать транслитерацию.
k. Не следует использовать венгерскую нотацию, т.е. не нужно кодировать тип в имени переменной.
5.2. Используемые для именования слова и сочетания
Слово
Парное
Назначение
enable
disable
Активация/деактивация какого-то элемента. В результате этого действия элемент (сущность) становится доступной (недоступной).
enabled
disabled
Элемент активен/неактивен, т.е. допускает или не допускает взаимодействие с ним.
checked
unchecked
Элемент отмечен/ не отмечен (выбран/не выбран). Наиболее соответствует ситуации, когда элемент выбирается в списке с флажками (checkbox'ами).
opened
-
Открыт/не открыт элемент. Например, этот признак может быть у модального окна, выпадающей части поля выбора, контекстного меню.
state
-
Используется для именования состояния элемента.
filter
-
Используется для именования фильтра.
factory
-
Фабрика каких-то объектов.
Last updated