Область применения: управляемое приложение, мобильное приложение, обычное приложение.
1. Описание процедур и функций рекомендуется выполнять в виде комментария к ним. Необходимость комментирования отдельных участков кода процедур и функций должна определяться разработчиком исходя из сложности и нестандартности конкретного участка кода.
При разработке на платформе 1С:Предприятие 8.3 текст комментария также выводится в контекстной подсказке процедур, функций и их параметров. Подробнее см. раздел «Контекстная подсказка при вводе текстов модулей» главы 27 «Инструменты разработки» в документации к платформе.
При разработке в 1C:Enterprise Development Tools (EDT) текст комментария также используется для уточнения типизации параметров и возвращаемого значения процедур и функций, и тем самым помогает выявлять ошибки кодирования на этапе разработки.
2. Обязательного комментирования требуют процедуры и функции входящие в программный интерфейс модулей - такие процедуры и функции предназначены для использования в других функциональных подсистемах (или в других приложениях), за которые могут отвечать другие разработчики, поэтому они должны быть хорошо документированы.
См. также: Ограничения на использование экспортных процедур и функций и Использование экспортных процедур и функций в модулях форм
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. В редких случаях, когда сразу несколько параметров имеют дополнительные типы, рекомендуется добавить секцию "Варианты вызова" (англ. "Сall 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. Код процедур и функций должен отделяться друг от друга в тексте модуля пустыми строками.
Пример описания функции с одним параметром:
// Определяет доступность ролей ИменаРолей текущему пользователю,
// а также доступность административных прав.
//
// Параметры:
// ИменаРолей - Строка - имена ролей, доступность которых проверяется, разделенные запятыми.
//
// Возвращаемое значение:
// Булево - Истина, если хотя бы одна из переданных ролей доступна текущему пользователю,
// либо у него есть административные права.
//
// Пример:
// Если РолиДоступны("ИспользованиеРассылокОтчетов,ОтправкаПоПочте") Тогда ...
//
Функция РолиДоступны(ИменаРолей) Экспорт
Пример описания процедуры без параметров:
// В обработчике события ПередЗаписью документа выполняется; // - очистка табличной части услуги, в случае если указан договор с комиссионером; // - проверка заполнения реквизита ЕдиницаИзмеренияМест табл. части Товары; // - синхронизация с "подчиненным" счетом-фактурой; // - заполнение склада и заказа покупателя в табличных частях Товары и ВозвратнаяТара; // - удаление неиспользуемых строк табличной части "Серийные номера"; // - заполнение переменной модуля объекта УдалятьДвижение. // Процедура ПередЗаписью() КонецПроцедуры
|
Для автоматического упорядочивания комментариев к процедурам или функциям с директивами компиляции можно воспользоваться приложенной обработкой ФорматированиеДирективКомпиляции.epf. Для этого необходимо:
|