Структура модуля и областей

Директивный

v8std#std455 v8std#std456 v8std#std437 v8std#std469 диагностикаNonStandardRegion диагностикаCodeOutOfRegion диагностикаCommentedCode

#структура-кода

Правило

Каждый модуль оформляется по стандартной структуре областей. Экспортный API — только в #Область ПрограммныйИнтерфейс, приватная реализация — в #Область СлужебныеПроцедурыИФункции. Публичный API не размазывается по модулю.

Порядок областей:

#Область ПрограммныйИнтерфейс — только экспортный API;
#Область СлужебныйПрограммныйИнтерфейс — экспорт для внутреннего слоя подсистемы;
#Область ОбработчикиСобытий — обработчики объекта/формы;
#Область СлужебныеПроцедурыИФункции — приватная реализация;
#Область Инициализация — минимальная инициализация без бизнес-логики.

Для модуля формы порядок свой (тот же принцип «событийное — отдельно от реализации»):

#Область ОписаниеПеременных;
#Область ОбработчикиСобытийФормы (ПриСозданииНаСервере, ПриОткрытии, …);
#Область ОбработчикиСобытийЭлементовШапкиФормы;
#Область ОбработчикиСобытийЭлементовТаблицыФормы<Имя> — по области на таблицу;
#Область ОбработчикиКомандФормы;
#Область СлужебныеПроцедурыИФункции.

Оформление: один оператор управления на строку, отступ табуляцией, ключевые слова запросов заглавными. Закомментированный код в основной ветке запрещён — история живёт в git.

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

Зачем

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

Правильно

#Область ПрограммныйИнтерфейс

// Возвращает актуальный курс валюты на дату.
Функция КурсВалюты(Валюта, Дата) Экспорт
    Возврат ПрочитатьКурс(Валюта, Дата);
КонецФункции

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

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

Функция ПрочитатьКурс(Валюта, Дата)
    // приватная реализация
КонецФункции

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

// Экспортный метод вперемешку с приватными, без областей —
// публичный API теряется в реализации.
Функция ПрочитатьКурс(Валюта, Дата)
    // ...
КонецФункции

Функция КурсВалюты(Валюта, Дата) Экспорт
    Возврат ПрочитатьКурс(Валюта, Дата);
КонецФункции

Когда не применять

Автогенерируемые модули (например, модули команд, создаваемые платформой) и пустые модули-заглушки. Во всех рукописных модулях правило действует всегда.

См. также

Код-стайл: корпоративные дополнения — guard-операторы, ограничение вложенности, префикс объектов.