Опис процедур і функцій

Автовпорядкування коментарів до процедур або функцій із директивами компіляції

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

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

Див. також: Обмеження на використання експортних процедур і функцій і Використання експортних процедур і функцій у модулях форм

4. Слід уникати коментарів, що не дають додаткових пояснень щодо роботи неекспортної процедури (функції).
Наприклад, неправильно:

// Процедура — обробник події "ПриОткрытии" форми
//
&НаКлиенте
Процедура ПриОткрытии()

// Процедура-обробник команди "Рассчитать"
//
&НаКлиенте
Процедура Рассчитать()

// Процедура-обробник події "ПриИзменении" елемента форми "РедактированиеТолькоВДиалоге"
//
&НаКлиенте
Процедура РедактированиеТолькоВДиалогеПриИзменении(Элемент)

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

// Функція повертає статтю руху грошових коштів за даними документа
Функція СтатьяДвиженияДенежныхСредств(ДанныеДокумента)

Цей коментар не надає жодної додаткової інформації про функцію.

5. Коментар розміщується перед оголошенням процедури (функції) і має такий вигляд.

5.1. Секція "Опис" містить словесний стислий опис призначення та/або принципів роботи процедури (функції). Може бути єдиною секцією для процедур без параметрів.

5.2. Секція "Параметри" описує параметри процедури (функції). Якщо їх немає, секція пропускається. Їй передує рядок "Параметри:", потім з нового рядка розміщуються описи всіх параметрів.

5.2.1. Опис параметра починається з нового рядка, далі ім’я параметра, потім дефіс і список типів (*), далі дефіс і текстовий опис параметра.
Наприклад:

// Параметри:
// ИменаРолей - Строка - імена ролей, доступність яких перевіряється, розділені комами.

Також для кожного параметра можна задати один або кілька додаткових описів типів параметра. Кожен додатковий опис починається з нового рядка, потім обов’язковий дефіс, далі список типів параметра(*), далі дефіс і текстовий опис.
Наприклад:

// Параметри:
// Реквизиты - Строка - імена реквізитів, перелічені через кому.
// Наприклад, "Код, Наименование, Родитель".
// - Структура, ФиксированнаяСтруктура - як ключ передається
// псевдонім поля для структури, що повертається з результатом,
// а як значення (необов’язково) фактичне ім’я поля в таблиці.
// Якщо значення не визначено, то ім’я поля береться з ключа.
// - Массив, ФиксированныйМассив – масив імен реквізитів.

5.3. Секція "Значення, що повертається" описує тип і вміст значення функції, що повертається. Для процедур ця секція відсутня. Їй передує рядок "Значення, що повертається:". Потім із нового рядка список типів (*), далі дефіс і текст.
Наприклад:

// Значення, що повертається:
// Булево - Істина, якщо хоча б одна з переданих ролей доступна поточному користувачеві,
// або він має адміністративні права.

5.4. Секція "Приклад" містить приклад використання процедури або функції. Їй передує рядок "Приклад:". Далі з нового рядка приклад використання.

(*) Примітка: під «списком типів» маються на увазі імена типів, розділені комами. Ім’я типу може бути простим (в одне слово) або складеним – у два слова, розділених крапкою.
Наприклад: Строка, Структура, СправочникСсылка.Сотрудники.

Під час розробки на платформі 1С:Підприємство 8.3 текст коментаря також виводиться в контекстній підказці процедур, функцій та їх параметрів. Докладніше див. розділ «Контекстна підказка під час введення текстів модулів» глави 26 «Інструменти розробки» в документації до платформи.

Приклад опису функції з одним параметром:

// Визначає доступність ролей ИменаРолей поточному користувачеві,
// а також доступність адміністративних прав.
//
// Параметри:
// ИменаРолей - Строка - імена ролей, доступність яких перевіряється, розділені комами.
//
// Значення, що повертається:
// Булево - Істина, якщо хоча б одна з переданих ролей доступна поточному користувачеві,
// або він має адміністративні права.
//
// Приклад:
// Якщо РолиДоступны("ИспользованиеРассылокОтчетов,ОтправкаПоПочте") Тоді ...
//
Функція РолиДоступны(ИменаРолей) Експорт

Приклад опису процедури без параметрів:

// В обробнику події ПередЗаписью документа виконується;
// - очищення табличної частини послуги, якщо зазначено договір із комісіонером;
// - перевірка заповнення реквізиту ЕдиницаИзмеренияМест табл. частини Товары;
// - синхронізація з "підпорядкованою" рахунком-фактурою;
// - заповнення складу й замовлення покупця в табличних частинах Товары та ВозвратнаяТара;
// - видалення невикористовуваних рядків табличної частини "Серийные номера";
// - заповнення змінної модуля об’єкта УдалятьДвижение.
//
Процедура ПередЗаписью()

КінецьПроцедури

6. Якщо потрібно прокоментувати процедуру або функцію, яка використовується з директивою компіляції, то спочатку слід розміщувати коментар, а потім —
директиву компіляції. Наприклад:

// Процедура — обробник події "ПриСозданииНаСервере" форми.
// Обробляє параметри форми та заповнює реквізити форми значеннями.
// А також виконує такі дії:
// ...
//
&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

Такий стиль розміщення коментаря дає змогу насамперед звертати увагу на визначення функції та директиву компіляції, а потім — на коментар, який може займати досить велику кількість рядків.

7. Код процедур і функцій має відокремлюватися один від одного в тексті модуля порожніми рядками.

Автовпорядкування коментарів до процедур або функцій із директивами компіляції

Для автоматичного впорядкування коментарів до процедур або функцій із директивами компіляції можна скористатися доданою обробкою ФорматированиеДирективКомпиляции.epf. Для цього необхідно:

1. Вивантажити модулі конфігурації (команда меню Конфігурація -> Вивантажити файли конфігурації...)
2. Відкрити обробку в режимі 1С:Підприємство і вказати каталог, до якого було вивантажено модулі — далі натиснути кнопку "Форматувати"
3. Завантажити модулі в конфігурацію (команда меню Конфігурація -> Завантажити файли конфігурації...)