v8-code-style/docs/contributing/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

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

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

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

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

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

ПРАВИЛЬНО

//@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 класс
3. Формируется описание в виде check.descriptions/check-id.md и check.descriptions/ru/check-id.md с детальным описанием
4. Ссылку на стандарт, по которому выполняется проверка, следует указывать в секции ## См. (или ## See) в файлах описаний check-id.md
5. Следует описывать все возможные варианты НЕПРАВИЛЬНО и ПРАВИЛЬНО которые находит проверка. Желательно использовать примеры из тестов.

Тип (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. имена параметров пишутся в сamelCase, начиная с маленькой буквы, без пробелов, второе слово и далее с заглавной буквы
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
• При наличии нескольких повторяющихся фрагментов кода с параметризацией и фильтрацией объектов - желательно создавать компонент com._1c.g5.v8.dt.check.components.IBasicCheckExtension для переиспользования.
• При необходимости использовать существующие компоненты com._1c.g5.v8.dt.check.components.ModuleTopObjectNameFilterExtension, com._1c.g5.v8.dt.check.components.TopObjectFilterExtension

Обязательные компоненты для каждой проверки

Добавьте одно из обязательных расширения проверок:

• StandardCheckExtension - для принадлежности проверки к функциональной опции включающей или отключающей проверки по 1С:Стандартам
• CommonSenseCheckExtension - для принадлежности проверки ко всем прочим полезным проверкам исходя из здравого смысла, "лучших практи" и т.д. которые не регламентируются стандартами 1С.

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

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

Текст ошибки

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

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

Примеры:

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

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

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

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

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

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

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

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

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

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

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