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

#std455

Область применения: управляемое приложение, мобильное приложение, обычное приложение.

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

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

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

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

1.2. Объемные разделы модулей рекомендуется разбивать на подразделы по функциональному признаку.

1.3. Разделы и подразделы оформляются в виде областей. При этом имена областей должны удовлетворять требованиям стандарта Правила образования имен переменных

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

русск.

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

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

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

англ.

#Region Public
// Enter code here.
#EndRegion

#Region Internal
// Enter code here.
#EndRegion

#Region Private
// Enter code here.
#EndRegion

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

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

русск.

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

англ.

#Region InfobaseUpdate
// Enter code here.
#EndRegion

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

русск.

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

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

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

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

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

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

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

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

англ.

#Region Variables

#EndRegion

#Region Public
// Enter code here.
#EndRegion

#Region EventHandlers
// Enter code here.
#EndRegion

#Region Internal
// Enter code here.
#EndRegion

#Region Private
// Enter code here.
#EndRegion

#Region Initialize

#EndRegion

Раздел «Программный интерфейс» содержит экспортные процедуры и функции, предназначенные для использования в других модулях конфигурации или другими программами (например, через внешнее соединение). Не следует в этот раздел помещать экспортные функции и процедуры, которые предназначены для вызова исключительно из модулей самого объекта, его форм и команд. Например, процедуры заполнения табличной части документа, которые вызываются из обработки заполнения в модуле объекта и из формы документа в обработчике команды формы не являются программным интерфейсом модуля объекта, т.к. вызываются только в самом модуле и из форм этого же объекта. Их следует размещать в разделе «Служебные процедуры и функции».
Раздел «Обработчики событий» содержит обработчики событий модуля объекта (ПриЗаписи, ПриПроведении и др.)
Раздел «Служебный программный интерфейс» имеет такое же предназначение, как и в общих модулях.
Раздел «Служебные процедуры и функции» имеет такое же предназначение, как и в общих модулях.

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

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

См. также: Правила создания модулей форм

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

русск.

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

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

англ.

#Region EventHandlers
// Enter code here.
#EndRegion

#Region Private
// Enter code here.
#EndRegion

Раздел «Обработчики событий» содержит процедуру-обработчик команды ОбработкаКоманды.
Раздел «Служебные процедуры и функции» имеет такое же предназначение, что и в общих модулях.

1.8. В модуле не должно быть пустых областей.

2. Общие требования к разделам программных модулей.

2.1. Заголовок модуля представляет собой комментарий в самом начале модуля. В заголовке модуля приводится его краткое описание и условия применения.
Например:

////////////////////////////////////////////////////////////////////////////////
// Клиентские процедуры и функции общего назначения:
// - для работы со списками в формах;
// - для работы с журналом регистрации;
// - для обработки действий пользователя в процессе редактирования
//   многострочного текста, например комментария в документах;
// - прочее.
//  
////////////////////////////////////////////////////////////////////////////////

Для модулей форм в заголовке рекомендуется размещать описание параметров формы.

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

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

русск.

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

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

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

англ.

#Region Variables

Var PresentationCurrency;
Var SupportEmail;
...

#EndRegion

2.3. Программный интерфейс. Экспортные процедуры и функции, составляющие программный интерфейс модуля, размещаются сразу же после описания переменных. Такие процедуры и функции предназначены для использования другими объектами конфигурации или другими программами (например, через внешнее соединение), поэтому должны быть расположены в модуле на "видном месте".

См. также: Описание процедур и функций

2.4.1. Обработчики событий формы, команд и элементов формы. Перед служебными процедурами и функциями в модуле формы располагаются обработчики событий формы, а также обработчики событий команд и элементов формы.

Методическая рекомендация (полезный совет)

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

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

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

Например, неправильно:

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

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

правильно:

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

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

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

Это требование обусловлено тем, что логически процедуры-обработчики событий не предназначены для использования в коде модуля, а вызываются непосредственно платформой. Смешение же этих двух сценариев в одной процедуре неоправданно усложняет ее логику и снижает ее устойчивость (вместо одного предусмотренного сценария вызова - по событию из платформы - код процедуры должен рассчитывать и на другие "прямые" вызовы из кода).

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

Методическая рекомендация (полезный совет)

2.5.1. Рекомендуется располагать обработчики, придерживаясь порядка их следования в описании встроенного языка.

2.6. Служебные процедуры и функции модуля, которые не являются обработчиками событий, а составляют внутреннюю реализацию модуля, размещаются в модуле следом за обработчиками событий.

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

Процедуры и функции, связанные между собой по характеру или по логике работы рекомендуется располагать вместе. В модулях форм не рекомендуется явно группировать процедуры и функции модуля на серверные, клиентские и функции без контекста, так как такое «технологическое» упорядочивание затрудняет понимание логики модуля, отвлекая внимание разработчика на детали ее реализации.

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

русск.

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

АдресПоддержки = "v8@1c.ru"; 
ВыполнитьИнициализацию();
...

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

англ.

#Region Initialize

SupportEmail = "v8@1c.ru";
Ctor();
...

#EndRegion

Для оформления разделов кода в виде областей рекомендуется воспользоваться приложенной обработкой.