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

1.1. У програмному модулі (загальні модулі, модулі об'єктів, модулі менеджерів об'єктів, модулі форм, команд тощо) у загальному випадку можуть бути присутні такі розділи в наведеній нижче послідовності:

• заголовок модуля
• розділ опису змінних
• експортні процедури та функції модуля, що становлять його програмний інтерфейс
• обробники подій об'єкта (форми)
• службові процедури та функції модуля
• розділ ініціалізації

Деякі розділи можуть бути присутні лише в модулях певного виду. Наприклад, обробники подій елементів форм можуть бути присутні лише в модулях форм, а розділ опису змінних і розділ ініціалізації не можуть бути визначені в неглобальних загальних модулях, модулях менеджерів об'єктів, наборів записів, значень констант і модулі сеансу.

Вимога щодо поділу коду модуля на розділи покликана підвищити читабельність коду та спростити внесення змін до коду різними авторами (розробниками) як під час колективної розробки, так і під час доопрацювання прикладних рішень на конкретних впровадженнях.

1.2. Шаблон (заготовка для копіювання) розділів для загальних модулів:

////////////////////////////////////////////////////////////////////////////////
// <Заголовок модуля: стислий опис і умови застосування модуля.>
// 
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
// ПРОГРАМНИЙ ІНТЕРФЕЙС

////////////////////////////////////////////////////////////////////////////////
// СЛУЖБОВІ ПРОЦЕДУРИ ТА ФУНКЦІЇ

• Розділ «Програмний інтерфейс» містить експортні процедури та функції, призначені для використання іншими об'єктами конфігурації або іншими програмами (наприклад, через зовнішнє з'єднання).
• Розділ «Службові процедури та функції» містить процедури та функції, що становлять внутрішню реалізацію загального модуля. У тих випадках, коли загальний модуль є частиною деякої функціональної підсистеми, що включає кілька об'єктів метаданих, у цьому розділі також можуть бути розміщені службові експортні процедури та функції, призначені лише для виклику з інших об'єктів цієї підсистеми.
  
  Для об'ємних загальних модулів рекомендується розбивати цей розділ на підрозділи за функціональною ознакою. Підрозділам передує коментар, який рекомендується оформлювати аналогічним чином. Наприклад:

////////////////////////////////////////////////////////////////////////////////
// Оновлення інформаційної бази

1.3. Шаблон оформлення розділів для модулів об'єктів, менеджерів, наборів записів, обробок, звітів тощо:

////////////////////////////////////////////////////////////////////////////////
// ПРОГРАМНИЙ ІНТЕРФЕЙС

////////////////////////////////////////////////////////////////////////////////
// ОБРОБНИКИ ПОДІЙ

////////////////////////////////////////////////////////////////////////////////
// СЛУЖБОВІ ПРОЦЕДУРИ ТА ФУНКЦІЇ

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

1.4. Шаблон оформлення розділів для модулів форм:

////////////////////////////////////////////////////////////////////////////////
// ОБРОБНИКИ ПОДІЙ ФОРМИ

////////////////////////////////////////////////////////////////////////////////
// ОБРОБНИКИ ПОДІЙ ЕЛЕМЕНТІВ ШАПКИ ФОРМИ

////////////////////////////////////////////////////////////////////////////////
// ОБРОБНИКИ ПОДІЙ ТАБЛИЦІ ФОРМИ <ІМ'Я ТАБЛИЦІ ФОРМИ>

////////////////////////////////////////////////////////////////////////////////
// ОБРОБНИКИ КОМАНД ФОРМИ

////////////////////////////////////////////////////////////////////////////////
// СЛУЖБОВІ ПРОЦЕДУРИ ТА ФУНКЦІЇ

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

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

2. Загальні вимоги до розділів програмних модулів.

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

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

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

2.2. Розділ опису змінних. Імена змінних призначаються згідно із загальними правилами утворення імен змінних, а їх використання описується у статті Використання глобальних змінних у програмних модулях.

Усі змінні модуля мають бути забезпечені коментарем, достатнім для розуміння їх призначення. Коментар рекомендується розміщувати в тому самому рядку, де оголошується змінна.
Приклад:

Перем ВалютаУчета Экспорт; // Валюта, у якій ведеться облік 
Перем АдресПоддержки Экспорт; // Адреса електронної пошти, куди надсилаються повідомлення про помилки

2.3. Програмний інтерфейс. Експортні процедури та функції, що становлять його програмний інтерфейс, розміщуються відразу після опису змінних. Такі процедури та функції призначені для використання іншими об'єктами конфігурації або іншими програмами (наприклад, через зовнішнє з'єднання), тому мають бути розташовані в модулі на "видному місці".

Див. також: Опис процедур і функцій

2.4.1 Обробники подій форми, команд і елементів форми. Перед службовими процедурами та функціями в модулі форми розташовуються обробники подій форми, а також обробники подій команд і елементів форми.

2.4.2. Для кожної події має бути призначена своя процедура-обробник. Якщо однакові дії мають виконуватися при виникненні подій у різних елементах форми, слід:

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

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

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

правильно:

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

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

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

Ця вимога зумовлена тим, що логічно процедури-обробники подій не призначені для використання в коді модуля, а викликаються безпосередньо платформою. Змішування ж цих двох сценаріїв в одній процедурі невиправдано ускладнює її логіку та знижує її стійкість (замість одного передбаченого сценарію виклику — за подією з платформи — код процедури має розраховувати й на інші "прямі" виклики з коду).

2.5. Обробники подій модулів об'єкта та менеджера об'єкта розміщуються після експортних, але до службових процедур і функцій модуля.

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

У тих випадках, коли загальний модуль є частиною деякої функціональної підсистеми, що включає кілька об'єктів метаданих, у цьому розділі також можуть бути розміщені службові експортні процедури та функції, призначені лише для виклику з інших об'єктів цієї підсистеми.

Процедури та функції, пов'язані між собою за характером або за логікою роботи, рекомендується розташовувати разом. Не рекомендується явно групувати процедури та функції модуля на серверні, клієнтські та функції без контексту, оскільки таке «технологічне» упорядкування ускладнює розуміння логіки модуля, відволікаючи увагу розробника на деталі її реалізації.

2.7. Розділ ініціалізації містить оператори, що ініціалізують змінні модуля або об'єкт (форму). Наприклад:

АдресПоддержки = "v8@1c.ru"; // Адреса для звернення до служби технічної підтримки
ВыполнитьИнициализацию();