1С:Предприятие 8.2 /
Разработчикам /
Соглашения при написании кода

Оглавление

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

Автоупорядочивание комментариев к процедурам или функциям с директивами компиляции

 

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

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

См. также: Ограничения на использование экспортных процедур и функций и Использование экспортных процедур и функций в модулях форм

Методическая рекомендация (полезный совет) 3. Прочие процедуры и функции (в том числе обработчики событий модулей форм, объектов, наборов записей, менеджеров значений и т.п.) рекомендуется комментировать, если требуется пояснить назначение процедуры (функции) или особенности её работы. Также рекомендуется описывать причины невыполнения некоторых действий, если они кажутся неочевидными для данной процедуры или функции. Но если процедура (функция) не сложна для понимания и ее назначение и порядок работы следуют из ее названия и имен формальных параметров, комментарий допускается не писать.

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

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

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

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

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

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

Этот комментарий не дает никакой дополнительной информации о функции.

5. Комментарий размещается перед объявлением процедуры (функции) и имеет следующий вид.

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

5.2. Секция "Параметры" описывает параметры процедуры (функции). Если их нет, секция пропускается. Предваряется строкой "Параметры:", затем с новой строки размещаются описания всех параметров.

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

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

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

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

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

//  Возвращаемое значение :
// Булево - Истина, если хотя бы одна из переданных ролей доступна текущему  пользователю ,
// либо у него есть административные права.

5.4. Секция "Пример" содержит пример использования процедуры, или функции. Предваряется строкой "Пример:". Далее с новой строки пример использования.

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

При разработке на платформе 1С:Предприятие 8.3 текст комментария также выводится в контекстной подсказке процедур, функций и их параметров. Подробнее см. раздел «Контекстная подсказка при вводе текстов модулей» главы 26 «Инструменты разработки» в документации к платформе.

Пример описания функции с одним параметром:

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

Пример описания процедуры без параметров:

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

КонецПроцедуры

6. Если требуется прокомментировать процедуру или функцию, которая используется с директивой компиляции, то вначале следует размещать комментарий, а затем -
директиву компиляции. Например:

// Процедура - обработчик события " ПриСозданииНаСервере " формы.
// Обрабатывает параметры формы и заполняет реквизиты формы значениями.
// А также выполняет следующие действия:
// ...
//
&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

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

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

Автоупорядочивание комментариев к процедурам или функциям с директивами компиляции

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

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

Нас находят: пример оглашения и описания процедуры без параметров, параметры процедуры ПередЗаписью(), процедура в 1с, https://stimul kiev ua/materialy htm?a=opisanie_protsedur_i_funktsiy, процдура для использованияконкретной роли 1с, 1с описание процедур и функций, Как поммотреть где используется процедура в 1с, Какие наименования функций или процедур нужно исправить?, разбираться и читать в коде 1с процедура и функция, 1с 77 описание функций