Перейти к содержанию

Экспортные процедуры/функции должны содержать описание

  1. Описание процедур и функций рекомендуется выполнять в виде комментария к ним. Необходимость комментирования отдельных участков кода процедур и функций должна определяться разработчиком исходя из сложности и нестандартности конкретного участка кода. При разработке на платформе 1С:Предприятие 8.3 текст комментария также выводится в контекстной подсказке процедур, функций и их параметров. Подробнее см. раздел «Контекстная подсказка при вводе текстов модулей» главы 27 «Инструменты разработки» в документации к платформе.
  2. Обязательного комментирования требуют процедуры и функции входящие в программный интерфейс модулей - такие процедуры и функции предназначены для использования в других функциональных подсистемах (или в других приложениях), за которые могут отвечать другие разработчики, поэтому они должны быть хорошо документированы.
  3. Прочие процедуры и функции (в том числе обработчики событий модулей форм, объектов, наборов записей, менеджеров значений и т.п.) рекомендуется комментировать, если требуется пояснить назначение процедуры (функции) или особенности её работы. Также рекомендуется описывать причины невыполнения некоторых действий, если они кажутся неочевидными для данной процедуры или функции. Но если процедура (функция) не сложна для понимания и ее назначение и порядок работы следуют из ее названия и имен формальных параметров, комментарий допускается не писать.

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

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

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

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

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

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

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

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

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

Например:

// Определяет доступность ролей ИменаРолей текущему пользователю,
// а также доступность административных прав.

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

Например:

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

5.2.2. Для параметров типа Структура и ТаблицаЗначений также задается описание их свойств и колонок, которые начинаются с новой строки и предваряются символом *.

Например:

// Параметры:
//   СтатусыСерий - ТаблицаЗначений - таблица значений с колонками:
//     * Серия - СправочникСсылка.СерииНоменклатуры - если серия указана и она может
//               использоваться с новым значением номенклатуры на указанном складе, 
//               то возвращается переданное значение; если нет - пустая ссылка
//     * СтатусУказанияСерий - Число - если серии указываются в ТЧ "Товары", то 
//               возвращается рассчитанный статус, если для переданной
//               номенклатуры/склада серии не используется - возвращается 0
//               иначе возвращается переданный статус.
//   ПараметрыУказанияСерий - Структура - см. НоменклатураКлиентСервер.ПараметрыУказанияСерий

Аналогично для параметров типа Массив:

// Параметры:
//  СведенияОбОбновлении  - Массив - cодержит структуры со свойствами:
//     * КодАдресногоОбъекта - Строка - код адресного объекта.
//     * Наименование        - Строка - наименование адресного объекта.
//     * Индекс              - Строка - индекс адресного объекта.
//     * ОбновлениеДоступно  - Булево - признак наличия обновления.
//

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

// Параметры:
//  СведенияОбОбновлении  - Массив - cодержит структуры со свойствами:
//     * КодАдресногоОбъекта - Структура - код адресного объекта.
//        ** КодРегиона             - Число - код региона (длина - 2).
//        ** КодНаселенногоПункта   - Число - код населенного пункта (длина - 3).
//        ** КодУлицы               - Число - код улицы (длина - 4).
//     * Наименование        - Строка    - наименование адресного объекта.
//     * ОбновлениеДоступно  - Булево    - признак наличия обновления.
//

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

Например:

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

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

Например:

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

Для возвращаемых значений также действуют требования п.5.2.2 и 5.2.3.

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

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

Например:

// ...
//
// Параметры:
//   Параметр1 - Тип11, Тип12        - ...
//   Параметр2 - Тип21, Тип22, Тип23 - ...
//
// Варианты вызова:
//   УниверсальнаяПроцедура(Тип11, Тип21) - описание ...
//   УниверсальнаяПроцедура(Тип12, Тип22) - описание ...
//   УниверсальнаяПроцедура(Тип11, Тип23) - описание ...
//

Процедура УниверсальнаяПроцедура(Параметр1, Параметр2) Экспорт

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

Например:

// См. процедуру УправлениеДоступом.ЗаполнитьНаборыЗначенийДоступа

5.6.1. Внутри текстового описания гиперссылки указываются в круглых скобках:

// Параметры:
//   СтатусыСерий - ТаблицаЗначений - таблица значений с колонками (см. функцию СерииКлиентСервер.СтатусыСерий).

5.6.2. Если в описании указана только одна эта ссылка, то без круглых скобок:

// Параметры:
//   ПараметрыУказанияСерий - Структура - см. функцию НоменклатураКлиентСервер.ПараметрыУказанияСерий

5.7. В случаях когда возникает необходимость отметить процедуру (функцию) как устаревшую, в первой строке ее описания размещается слово "Устарела".

Например:

// Устарела. Следует использовать новую (см. ОбщегоНазначения.ЕстьРоль)
// ... 
Функция РолиДоступны(ИменаРолей) Экспорт
  1. Если требуется прокомментировать процедуру или функцию, которая используется с директивой компиляции, то вначале следует размещать комментарий, а затем - директиву компиляции.

Например:

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

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

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

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

Например: Строка, Структура, СправочникСсылка.Сотрудники.

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

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

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

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

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

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

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