# 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) в проекте, если контрибьютор считает, что ее необходимо активировать всегда.