v8-code-style/Check_Convention.md

# Check convention - Соглашения проверок


## Регистрация проверки

### Категория проверки

Проект 1С:Стандарты разработки V8 поставляет категории в разрезе типов объектов в метаданных.
Следует указывать категорию для каждой проверки из соответствующего бандла, где размещен класс проверки.

### Код проверки

1. cebab-case (кебаб-кейс) - с маленькой буквы, без пробелов, использовать тире между словами. Не следует использовать `CamelCase` т.к. он менее читабельный.
2. Префикс типа объекта (md, form, right, ql, dcs и т.д) - код должен содеражть префикс типа объекта или имя уникального класса объекта (`common-module`, `catalog`, `role` и т.д.) что бы не допустить неоднозначности толкования к чему применяется проверка
3. Префикс вендора (`v8codestyle`) в коде проверки не используется
4. Константа с кодом проверки должна быть приватной

#### Код проверки должен отражать смысл проверяемой проблемы.

Следует отражать в коде проверки находимую проблему или группу проблем (если проверка выполняет множество однотипных проверок).

Код проверки не должен состоять лишь из имен найденных объектов. 

НЕПРАВИЛЬНО:

Здесь ключ проверки отражает только имена объектов которые проверяет:
```
module-method-check
function-type-check
```


Не следует в коде проверки отражать процесс поиска проблемной ситуации.

НЕПРАВИЛЬНО:

```
check-method-usage
```

ПРАВИЛЬНО:

```
method-never-used
```

#### Код проверки должен корректно читаться вместе с аннотацией

Это чуть более актуально для проверок по модулю - т.к. это будет везде визуально читаться.

Для других типов проверок (по метаданным) аналогичное правило подходит, хоть и не будет постоянно отображаться везде в интерфейсе (при открытии доп.формы).

НЕПРАВИЛЬНО:

```bsl
//@skip-check check-method-never-used
```

ПРАВИЛЬНО

```bsl
//@skip-check method-never-used
```

#### Слова-паразиты

Следует избегать использования "слов-паразитов", которые не добавляют никакого смысла в код проверки, например слова: check, error, warning, артикли a, the, to, is, are и т.д. problem, valid

НЕПРАВИЛЬНО

```
check-method-is-empty
to-find-my-awesome-problem
```

ПРАВИЛЬНО:

```
method-empty
awesome-problem
```

#### Разделение по типам объектов метаданных

Из кода проверки желательно сразу понимать к какому типу объектов она имеет отношение. Обычно это следует от типа ТОП-объектов (md, form, module/bsl, dcs, ql, moxel).  Если проверка диагностирует проблему в подчиненном объекте имя которого уникально - можно не указывать префикс топ-объекта.

НЕПРАВИЛЬНО:

```
attribute-type-empty
parameter-name-too-short
```

ПРАВИЛЬНО:

```
form-attribute-type-empty
md-attribute-type-empty
method-parameter-name-too-short
form-parameter-name-too-short
module-standard-regions
function-has-no-return-type
```

### Наименование проверки

- Что проверяем, какую ошибку находит
- Существительное, в именительном падеже
- Наименование должно быть локализовано через NLS класс


### Детальное описание

1. Следует указывать описание при регистрации проверки в классе.
2. Детальное описание должно быть локализовано через NLS класс
2. Формируется описание в виде `check.descriptions/check-id.md` и `check.descriptions/ru/check-id.md` с детальным описанием
3. Ссылку на стандарт, по которому выполняется проверка, следует указывать в секции `## См.` (или `## See`) в файлах описаний `check-id.md`
4. Следует описывать все возможные варианты `НЕПРАВИЛЬНО` и `ПРАВИЛЬНО` которые находит проверка. Желательно использовать примеры из тестов.

### Тип (issueType)

Тип найденной проблемы/диагностики

- `ERROR` - Ошибка в приложении
- `WARNING` - Предупреждение о проблеме в приложении
- `SECURITY` - Уязвимость в приложении
- `PERFORMANCE` - Проблема производительности приложения
- `PORTABILITY` - Проблема универсальности метаданных и кода приложения.
- `LIBRARY_DEVELOPMENT_AND_USAGE` - Проблема внедрения библиотеки или нарушение принципов библиотечной разработки.
- `CODE_STYLE` - Соглашения при написании кода, некачественный код
- `UI_STYLE` - Проблема проектирования UI
- `SPELLING` - Опечатка в тексте, коде, в именах метаданных

### Критичность (severity)

Необходимо установить критичность найденной ошибки по умолчанию.
Критичность необходимо устанавливать адекватную проблеме уровню проблемы в приложении.

- `BLOCKER` - ошибку необходимо исправлять немедленно
- `CRITICAL` - Критичная проблема, необходимо исправлять в первую очередь
- `MAJOR` - Обычная проблема, исправлять следут в обычном порядке
- `MINOR` - Незначительная проблема
- `TRIVIAL` - Тривиальная проблема

### Сложность (complexity)

- `NORMAL` - Сложность алгоритма поиска ошибочной ситуации низкая, не выполянется обращение к объектам из других ресурсов.
- `COMPLEX` - Большое количество вычислений, обращение к объектам из других ресурсов


### Параметры

Принципы создания параметров:
- Возможность внести исключения в правило поиска проблемных мест
- Нет смысла в параметрах если проверяется единственный объект и какое-либо исключение равно отключению проверки
- Используйте паттерны в параметрах для поиска исключений
- Любые константные значения (текстовые, числовые, с большой вариабельностью, Булево), которое имеют отношение к логике проверки, следует задавать через параметры

Типовые примеры:
- Исключение по имени метаданного
- Длина, количество символов и т.д. - числовые значения в проверке обычно являются кандидатами для вынесения в параметры

Соглашения при создании параметров:
1. имена параметров должны быть понятны в контексте проверки
2. имена параметров пишутся в `camelCase`, начиная с маленькой буквы, без пробелов, второе слово и далее с заглавной буквы
3. Константа с именем параметра должна быть публичной
4. Заголовок параметра должен быть локализован через NLS класс


### Компоненты, расширяющие функциональность

- Проверки, проверяющие 1 объект на наличие ошибок, в общем случае следует наследовать от `com._1c.g5.v8.dt.check.components.BasicCheck` или аналогичных для специфичных областей `com.e1c.g5.v8.dt.bsl.check.DocumentationCommentBasicDelegateCheck`, `com.e1c.g5.v8.dt.ql.check.QlBasicDelegateCheck`
- При наличии нескольих повторяющихся фрагментов кода c параметризацией и фильтрацией объектов - желательно создавать компонент `com._1c.g5.v8.dt.check.components.IBasicCheckExtension` для переиспользования.
- При необходимости использовать существующие компоненты `com._1c.g5.v8.dt.check.components.ModuleTopObjectNameFilterExtension`, `com._1c.g5.v8.dt.check.components.TopObjectFilterExtension`



## Логика проверки / код проверки

- В общем случае, при регистрации проверки, следует выбирать тот объект, в котором будет найдена ошибка, от этого объекта следует вычислять/находить другие зависимые, влияющие объекты.
- Код поиска ошибочной ситуации следует строить максимально оптимальным способом.
- Не следует ухудшать читаемость кода, за исключением производительности.

### Текст ошибки

Текс ошибки должен отвечать на вопрос:

1. Какой объект содержит ошибку? В одной строке может быть несколько очень разных объектов. Объект желательно писать в именительном падеже.
2. В чем именно ошибка, что в коде не правильно?
3. При этом, указание наименования объекта - не обзятельно, но желательно - если оно не портит фразу.
4. Указание значений параметров в сообщении, если от значений зависит наличие ошибки.
5. Сообщение должно быть локализовано через NLS класс.

Примеры:
1. Переменная не была инициализирована
2. Конфигурация содержит некоректный режим блокировки данных
3. Метод пустой
4. Метод не используется
5. Длина имени объекта метаданного должна быть меньше чем `80`

### Как проверять

1. Одна проверка должна находить одно проблемное место в одном типе объектов
2. Учитывать параметры, а не хардкод конкретных значений
3. Учитывать исключения, место проверки исключения следует выбирать из оптимальности алгоритма

При регистрации проверки следует указывать все фичи, от которых зависит логика проверки - это означает, что при изменении любого из второстепенных свойств объекта будет выполнена перевалидация по текущей проверке.

## Тестирование проверок

1. Для каждого варианта ошибочного состояния необходим тест. Если тестовые ситуации слишком разные, желательно написать различные тесты
2. Для корректного состояния необходимо добавить тест, в котором проверка не должна находить проблему.

Каждый корректный и ошибочный вариант должны быть добавлены в разделы "ПРАВИЛЬНО" и "НЕПРАВИЛЬНО" описания проверки


## Проверка не по стандарту

Если какая-либо проверка напрямую не описана в одном из стандартов, но при этом является полезной - такую проверку можно размещать в этом проекте.

Проверку следует регистрировать по умолчанию выключенной - таким образом каждый проект 1С:Предприятия может сам решить какие дополнительные проверки активировать.

Регистрация проверки не по стандарту, включенной по умолчанию, следует явно описывать в задаче (issue) в проекте, если контрибьютор считает, что ее необходимо активировать всегда.