v8-code-style Стандарт 455: Структура модуля (анализ возможных проверок)

Структура модуля

Возможные проверки

[x] module-structure-top-regions
#532
#533 #488 #614 Модуль содержит области только из списка стандартрных верхнеуровневых областей по типу модуля.

Параметры проверки: - список дополнительных кастомных верхнеуровневых областей, общий для всех типов модулей. - опция дополнительной проверки порядка стандартных областей, кастомные области в проверке не учитываются #488 - опция дополнительной проверки дублей стандартных областей #614

текст из стандарта:

1.1. В программном модуле (общие модули, модули объектов, модули менеджеров объектов, модули форм, команд и т.п.) в общем случае могут присутствовать следующие разделы в приведенной ниже последовательности:

заголовок модуля

раздел описания переменных

экспортные процедуры и функции модуля, составляющие его программный интерфейс

обработчики событий объекта (формы)

служебные процедуры и функции модуля

раздел инициализации

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

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

[x] module-structure-method-in-regions #373 Метод расположен в корректной стандартной области (за исключением области описания переменных и области инициализации).

1.4. Шаблон (заготовка для копирования) разделов для общих модулей:
русск.

#Область ПрограммныйИнтерфейс
// Код процедур и функций
#КонецОбласти

#Область СлужебныйПрограммныйИнтерфейс
// Код процедур и функций
#КонецОбласти

#Область СлужебныеПроцедурыИФункции
// Код процедур и функций
#КонецОбласти
англ.

#Region Public
// Enter code here.
#EndRegion

#Region Internal
// Enter code here.
#EndRegion

#Region Private
// Enter code here.
#EndRegion
Раздел «Программный интерфейс» содержит экспортные процедуры и функции, предназначенные для использования другими объектами конфигурации или другими программами (например, через внешнее соединение). Раздел «Служебный программный интерфейс» предназначен для модулей, которые являются частью некоторой функциональной подсистемы. В нем должны быть размещены экспортные процедуры и функции, которые допустимо вызывать только из других функциональных подсистем этой же библиотеки. Раздел «Служебные процедуры и функции» содержит процедуры и функции, составляющие внутреннюю реализацию общего модуля. В тех случаях, когда общий модуль является частью некоторой функциональной подсистемы, включающей в себя несколько объектов метаданных, в этом разделе также могут быть размещены служебные экспортные процедуры и функции, предназначенные только для вызова из других объектов данной подсистемы.

[x] module-structure-init-code-in-regions #603 #535 #375 Код инициализации расположен в области не предназначенной для инициализации.

текст из стандарта:

2.7. Раздел инициализации содержит операторы, инициализирующие переменные модуля или объект (форму). Например:
русск.

#Область Инициализация

АдресПоддержки = "[email protected]"; 
ВыполнитьИнициализацию();
...

#КонецОбласти
англ.

#Region Initialize

SupportEmail = "[email protected]";
Ctor();
...

#EndRegion

[x] module-structure-var-in-regions #534 #531 #200 Переменная объявлена в области не предназначенной для описания переменных.

текст из стандарта:

2.2. Раздел описания переменных. Имена переменных назначаются согласно общим правилам образования имен переменных, а их использование описывается в статье Использование глобальных переменных в программных модулях.

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

#Область ОписаниеПеременных

Перем ВалютаУчета;
Перем АдресПоддержки;
...

#КонецОбласти
англ.

#Region Variables

Var PresentationCurrency;
Var SupportEmail;
...

#EndRegion

[x] module-structure-event-regions #773 #330 Проверка области Обработка событий (кроме форм).

текст из стандарта:

1.5. Шаблон оформления разделов для модулей объектов, менеджеров, наборов записей, обработок, отчетов и т.п.: 1.7. Шаблон оформления разделов для модулей команд:
русск.

#Область ОбработчикиСобытий
// Код процедур и функций
#КонецОбласти
англ.

#Region EventHandlers
// Enter code here.
#EndRegion
Раздел «Обработчики событий» содержит обработчики событий модуля объекта (ПриЗаписи, ПриПроведении и др.)

[x] module-structure-form-event-regions Проверка областей событий формы (форма, шапка, таблица и команды).

Параметр проверки:
- Многоуровневое вложение областей

текст из стандарта:

1.6. Шаблон оформления разделов для модулей форм:
русск.

#Область ОписаниеПеременных

#КонецОбласти

#Область ОбработчикиСобытийФормы
// Код процедур и функций
#КонецОбласти

#Область ОбработчикиСобытийЭлементовШапкиФормы
// Код процедур и функций
#КонецОбласти

#Область ОбработчикиСобытийЭлементовТаблицыФормы<ИмяТаблицыФормы>
// Код процедур и функций
#КонецОбласти

#Область ОбработчикиКомандФормы
// Код процедур и функций
#КонецОбласти

#Область СлужебныеПроцедурыИФункции
// Код процедур и функций
#КонецОбласти
англ.

#Region Variables

#EndRegion

#Region FormEventHandlers
// Enter code here.
#EndRegion

#Region FormHeaderItemsEventHandlers
// Enter code here.
#EndRegion

#Region FormTableItemsEventHandlers<FormTableName>
// Enter code here.
#EndRegion

#Region FormCommandsEventHandlers
// Enter code here.
#EndRegion

#Region Private
// Enter code here.
#EndRegion
Раздел «Обработчики событий формы» содержит процедуры-обработчики событий формы: ПриСозданииНаСервере, ПриОткрытии и т.п. Раздел «Обработчики событий элементов шапки формы» содержит процедуры-обработчики элементов, расположенных в основной части формы (все, что не связано с таблицами на форме). В разделах «Обработчики событий элементов таблицы формы <имя таблицы формы>» размещаются процедуры-обработчики таблиц формы и элементов таблиц. Для процедур-обработчиков каждой таблицы должен быть создан свой раздел. Раздел «Обработчики команд формы» содержит процедуры-обработчики команд формы (имена которых задаются в свойстве Действие команд формы). Раздел «Служебные процедуры и функции» имеет такое же предназначение, что и в общих модулях.

[x] module-structure-non-export-in-api-regions Не экспортный метод находится в интерфейсных областях - реализовано с проверкой module-structure-method-in-regions
[x] form-commands-one-action-handler #856 Один обработчик выполнения назначен нескольким элементам

текст из стандарта:

2.4.3. У каждого события должна быть назначена своя процедура-обработчик. Если одинаковые действия должны выполняться при возникновении событий в разных элементах формы следует:

создать отдельную процедуру (функцию), выполняющую необходимые действия

для каждого элемента формы создать отдельный обработчик с именем, назначаемым по умолчанию

из каждого обработчика вызвать требуемую процедуру (функцию).

Например, неправильно:
&НаКлиенте
Процедура ПоИсполнителюПриИзменении(Элемент)
 ПараметрыОтбора = Новый Соответствие();
 ПараметрыОтбора.Вставить("ПоАвтору", ПоАвтору);
 ПараметрыОтбора.Вставить("ПоИсполнителю", ПоИсполнителю);
 УстановитьОтборСписка(Список, ПараметрыОтбора);
КонецПроцедуры

&НаКлиенте
Процедура ПоАвторуПриИзменении(Элемент)
 ПоИсполнителюПриИзменении(Неопределено);
КонецПроцедуры
правильно:

&НаКлиенте
Процедура ПоИсполнителюПриИзменении(Элемент)
 УстановитьОтбор();
КонецПроцедуры

&НаКлиенте
Процедура ПоАвторуПриИзменении(Элемент)
 УстановитьОтбор();
КонецПроцедуры

&НаСервере
Процедура УстановитьОтбор()
 ПараметрыОтбора = Новый Соответствие();
 ПараметрыОтбора.Вставить("ПоАвтору", ПоАвтору);
 ПараметрыОтбора.Вставить("ПоИсполнителю", ПоИсполнителю);
 УстановитьОтборСписка(Список, ПараметрыОтбора);
КонецПроцедуры 
Это требование обусловлено тем, что логически процедуры-обработчики событий не предназначены для использования в коде модуля, а вызываются непосредственно платформой. Смешение же этих двух сценариев в одной процедуре неоправданно усложняет ее логику и снижает ее устойчивость (вместо одного предусмотренного сценария вызова - по событию из платформы - код процедуры должен рассчитывать и на другие "прямые" вызовы из кода).

Jul 26 '22 23:07 iArtemv

Проверка module-structure-top-region уже есть в ModuleStructureTopRegionCheck - видимо ее надо дорабатывать

Jul 27 '22 10:07 marmyshev

Не получается разместить обработчики для подписок (например перед записью или при записи) без предупреждений: ругается или module-structure-method-in-regions или module-structure-event-regions : одна проверка говорит что процедура должна быть в программной интерфейсе, а другая - в обработчиках событий. EDT: 2022.1.0 v8codestyle: 0.3.0.136

Aug 06 '22 06:08 ilya2184

@ilya2184 Добрый день, скоро появится еще одна проверка структуры модуля, которая скажет, что в общем модуле не может быть топ области ОбработчикиСобытий (область ОбработчикиСобытий можно перенести, например, внутрь ПрограммныйИнтерфейс) А за ошибку спасибо, поправим.

Aug 06 '22 07:08 iArtemv

Да я в обще-то не против перенести внутрь, но у меня так тоже не получается. Я если честно - даже не знаю - как правильно размещать процедуры подписок: я вроде знаю что в общем модуле обработчиков событий быть не может, но тогда процедуры подписок на события это что? Мы не против даже считать это не обработчиками событий, но module-structure-method-in-regions - считает их обработчиками событий UPD: я понял module-structure-method-in-regions ошибочно рекомендует разместить подписки в обработчиках событий.

Aug 06 '22 08:08 ilya2184

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

Aug 06 '22 08:08 iArtemv

v8-code-style v8-code-style copied to clipboard

Стандарт 455: Структура модуля (анализ возможных проверок)

Структура модуля

v8-code-style
v8-code-style copied to clipboard