#std453

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

1.

Описывайте процедуры и функции в комментарии к ним.

Текст комментария отображается в контекстной подсказке процедур, функций и их параметров.

При разработке в 1C:Enterprise Development Tools (EDT) комментарий также используется для уточнения типизации параметров и возвращаемого значения процедур и функций и помогает выявлять ошибки кодирования на этапе разработки.

2.

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

См. также:

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

3.

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

Если процедура (функция) проста для понимания и ее назначение и порядок работы следуют из названия и имен формальных параметров, комментарий можно не писать.

4.

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

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

Неправильно

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

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

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

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

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

5.

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

5.1.

Секция // Описание» (англ. // Description) содержит назначение процедуры (функции), достаточное для понимания сценариев использования без просмотра исходного кода. Также может содержать краткое описание принципов работы и перекрестные ссылки на связанные процедуры и функции.

Может быть единственной секцией для процедур без параметров. Описание не должно совпадать с именем процедуры (функции). Для процедур и функций секция должна начинаться с глагола. Для функций это, как правило, «Возвращает…». Если возвращаемый результат не основной в работе функции, начинайте с основного действия: «Проверяет…», «Сравнивает…», «Вычисляет…» и т.п. Не начинайте описание с избыточных слов «Процедура...», «Функция...» или с имени самой процедуры (функции), если смысл от удаления не меняется.

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

Неправильно

// Конструктор объекта WSПрокси.
// ...
Функция WSПрокси(ПараметрыПрокси) Экспорт
...

// Функция СтрокаТаблицыЗначенийВСтруктуру создает структуру со свойствами, соответствующими...
Функция СтрокаТаблицыЗначенийВСтруктуру(СтрокаТаблицыЗначений) Экспорт
...

Правильно:

Правильно

// Создает прокси на основе определения веб-сервиса и связывает
// его с точкой подключения веб-сервиса.
// В дополнении к платформенному конструктору Новый WSПрокси:
//  - включает в себя вызов конструктора WSОпределения;
//  - на время сеанса кэширует файл WSDL для оптимизации частых обращений к веб-сервису;
//  - не требует явного указания ИнтернетПрокси (он подставляется автоматически, если настроен);
//  - выполняет быструю проверку доступности веб-сервиса с помощью операции Ping.
// ...
Функция WSПрокси(ПараметрыПрокси) Экспорт
...

// Создает структуру со свойствами, соответствующими...
Функция СтрокаТаблицыЗначенийВСтруктуру(СтрокаТаблицыЗначений) Экспорт
...

5.2.

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

5.2.1.

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

Выбирайте имя параметра так, чтобы назначение было понятно в контексте функции без дополнительных пояснений.

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

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

В качестве типов значений используйте только существующие в платформе типы, а также специальные типы, предусмотренные в EDT: ОпределяемыйТип.<Имя>, СправочникСсылка, ОбъектМетаданныхОтчет, РасширениеДекорацииФормыДляНадписи и т.п.

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

Неправильно

// КоллекцияСтрок - КоллекцияЗначений – коллекция для сравнения;
// ФормируемыйОтчет - ОбъектМетаданных: Отчет
// ПрисоединенныйФайлОбъект - элемент справочника файлов.

Правильно:

Правильно

// КоллекцияСтрок – ТаблицаЗначений, Массив, СписокЗначений – коллекция для сравнения.
// ФормируемыйОтчет – ОбъектМетаданныхОтчет
// ПрисоединенныйФайлОбъект - ОпределяемыйТип.ПрисоединенныйФайлОбъект - элемент справочника файлов.

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

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

Неправильно

// Проверяет, что переданные адреса включены в задачу. Если проверка не проходит – генерируется исключение.
//
// Параметры:
//  Адреса - Строка - строка, содержащая электронные адреса
//  ЗадачаИсполнителя - ЗадачаСсылка.ЗадачаИсполнителя – проверяемая задача
//
Процедура ПроверитьАдресаЗадачи(Адреса, ЗадачаИсполнителя)
...

Правильно:

Правильно

// Проверяет, что переданные адреса включены в задачу. Если проверка не проходит – генерируется исключение.
//
// Параметры:
//  Адреса - Строка - содержит электронные адреса, разделенные запятой. Например, support@mycorp.ru,v8@localdomain.
//  ЗадачаИсполнителя - ЗадачаСсылка.ЗадачаИсполнителя
//
Процедура ПроверитьАдресаЗадачи(Адреса, ЗадачаИсполнителя)
...

В данном примере текстовое описание для параметра Адреса нужно, чтобы:

• указать правило передачи нескольких адресов (через запятую);
• привести пример.

Для параметра ЗадачаИсполнителя описание не требуется.

5.2.2.

Для параметров типа Структура и ТаблицаЗначений (ДеревоЗначений) в описании типа указывайте ссылку на функцию, выходным значением которой является эта структура или таблица значений. Например, ссылку на функцию-конструктор.

Пример:

Пример

// Заполняет цены в строке табличной части
// Параметры:
//  ТекущаяСтрока – СтрокаТабличнойЧасти
//  ПараметрыЗаполненияЦен – см. ЦенообразованиеСервер.ПараметрыЗаполненияЦен
//
Процедура ЗаполнитьЦеныВСтрокеТЧ(ТекущаяСтрока, ПараметрыЗаполненияЦен);

В редких случаях, когда метод обрабатывает коллекции универсальным образом, не описывайте свойства и колонки параметра. Достаточно указать тип Структура или ТаблицаЗначений (ДеревоЗначений).

5.2.3.

Для параметров типа Массив указывайте тип элементов с помощью ключевого слова Из (англ. Of).

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

Неправильно

// МассивПеренаправленныхЗадач - Массив - массив перенаправленных задач.
// МассивПеренаправленныхЗадач - Массив - задачи (ЗадачаСсылка.ЗадачаИсполнителя), перенаправленные другому исполнителю.

Правильно:

Правильно

// СведенияОбОбновлении  - Массив из см. ОбновлениеИнформационнойБазы.ПараметрыОбновления

Не указывайте тип элементов массивов только в методах, которые работают с массивами универсальным образом. Например, в Библиотеке стандартных подсистем есть методы ДополнитьМассив, УдалитьВсеВхожденияЗначенияИзМассива и т.д.

5.2.4.

Для параметра типа СтрокаТаблицыЗначений (СтрокаДереваЗначений) можно задать состав свойств, соответствующий колонкам его таблицы-владельца (дерева-владельца).

Например:

Пример

// СведенияОРегионе – СтрокаТаблицыЗначений: см. РегистрыСведений.АдресныеОбъекты.КлассификаторСубъектовРФ

КлассификаторСубъектовРФ — экспортная функция модуля менеджера регистра сведений АдресныеОбъекты, которая возвращает таблицу значений.

5.2.5.

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

Например:

Пример

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

5.2.6.

Описания также могут задаваться с помощью ссылки на функцию-конструктор в формате // см. ПутьКФункции (англ. // see MethodPath).

Например:

Пример

// ПараметрыУказанияСерий - см. НоменклатураКлиентСервер.ПараметрыУказанияСерий
// Дубли - см. ОбработкаОбъект.ПоискИУдалениеДублей.ГруппыДублей
// РеквизитыКомпонент - Массив из см. ВнешниеКомпоненты.РеквизитыКомпоненты

При разработке кода, обращающегося к реквизитам конкретного объекта метаданных или формы, можно ссылаться на типы реквизитов этого объекта (формы):

Пример

//  Запросы - см. Обработка.КонсольЗапросов.ТабличнаяЧасть.Запросы
//  ТипыДанных - см. Обработка.КонсольЗапросов.Реквизит.ДоступныеТипыДанных
//  Вложения - см. Справочник.ШаблоныСообщений.ФормаЭлемента.Вложения
//  КонтактнаяИнформация - см. Документ.ЗаказПокупателя.ФормаДокумента.Объект.КонтактнаяИнформация

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

Пример

// См. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту
//
Процедура ПриОпределенииКомандПодключенныхКОбъекту(НастройкиФормы, Источники, ПодключенныеОтчетыИОбработки, Команды) Экспорт

// Параметры:
//  НастройкиФормы - см. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту.НастройкиФормы
//  Источники - см. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту.Источники
//  ПодключенныеОтчетыИОбработки - см. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту.ПодключенныеОтчетыИОбработки
//  Команды - см. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту.Команды
//
Процедура ПриОпределенииКомандПодключенныхКОбъекту(НастройкиФормы, Источники, ПодключенныеОтчетыИОбработки, Команды) Экспорт

5.3.

Секция // Возвращаемое значение: (англ. // Returns:) описывает тип и содержание возвращаемого значения функции. Для процедур секция отсутствует. Секция начинается строкой «Возвращаемое значение:». Затем с новой строки указывается тип возвращаемого значения, дефис и текст описания. Если возвращаемое значение составного типа, каждый тип пишется с новой строки и с дефиса.

Например:

Пример

// Возвращаемое значение:
//  Строка

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

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

// Возвращаемое значение:
//  - СправочникСсылка.Пользователи
//  - СправочникСсылка.ВнешниеПользователи

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

Формат описания возвращаемого значения с типом Массив аналогичен п. 5.2.3. Формат описания возвращаемого значения с типом Структура и ТаблицаЗначений описан в стандарте «Структуры и таблицы значений в качестве параметров процедур и функций».

5.4.

Секция // Пример:» (англ. // Example:) содержит пример использования процедуры или функции. Секция начинается строкой «Пример:». Далее с новой строки приводится пример использования. Имя процедуры (функции) пишите вместе с именем общего модуля, в котором она расположена. Из примера должно быть понятно, что передается на входе и что возвращается на выходе.

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

Неправильно

// Пример:
//  ПодставитьПараметрыВСтроку(ШаблонСтроки, СтрокаЗамены);

Правильно:

Правильно

// Пример:
//  СтроковыеФункцииКлиентСервер.ПодставитьПараметрыВСтроку(НСтр("ru='%1 пошел в %2'"), "Вася", "Зоопарк") = "Вася пошел в Зоопарк".

5.4.1.

В переопределяемых модулях в секции «Пример» приводите пример реализации переопределяемой процедуры, а не пример ее вызова. Например, для процедуры ПриОпределенииОбщихПараметровБазовойФункциональности(ОбщиеПараметры):

Пример

// Пример:
//  ОбщиеПараметры.МинимальноНеобходимаяВерсияПлатформы = "8.3.4.365";
//  ОбщиеПараметры.РекомендуемыйОбъемОперативнойПамяти = 2;

5.5.

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

Например:

Пример

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

5.6.

В любом месте документирующего комментария можно добавить переход к другим объектам конфигурации, процедурам и функциям (в том числе к функциям-конструкторам структур). В 1C:Enterprise Development Tools среда оформит такие переходы в виде гиперссылки.

Например:

Пример

// Описание универсальной процедуры.
//
// См. УправлениеДоступом.ЗаполнитьНаборыЗначенийДоступа
//
// Параметры:
//   Параметр1 – Произвольный – описание параметра см. Справочник.Контрагенты.
//
Процедура УниверсальнаяПроцедура(Параметр1)

5.7.

Если нужно пометить процедуру (функцию) как устаревшую, в первой строке описания используйте слово // Устарела (англ. // Deprecated).

Например:

Пример

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

6.

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

Например:

Пример

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

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

7.

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

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

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

Пример

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

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

Пример

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

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

Источник

https://its.1c.ru/db/v8std#content:453