Правильное оформление описания процедуры позволяет разработчику быстро и точно определять назначение процедуры, какие входные параметры и какого типа используются процедурой, а также примеры использования.
В этой статье мы собрали для вас правила оформления описания процедуры в модулях конфигурации согласно системе стандартов и методик разработки конфигурации.
Инструкции составлены на основе методических материалов проверенного источника — 1С:ИТС.
Общие правила
Описание процедуры выполняется в виде комментария («//…»).
Если процедура является простой, её назначение и порядок работы следуют из её названия и имён параметров, то описание процедуры можно не указывать.
Не стоит писать комментарий к процедуре, если он никак не поясняет или никак не дополняет логику работу процедуры.
// Простить и забыть Процедура УдалитьОбъект()…
Между секциями комментария должна быть пустая строка комментария для удобства чтения:
// Заполняет таблицу ценами… // // Параметры: // ТаблицаТоваров - ТаблицаЗначений – таблица с товарами… // ПараметрыЗаполненияЦен - см. ЦенообразованиеСервер.ПараметрыЗаполненияЦен //
Описание указывается непосредственно перед самой процедурой, а если указана директива компиляции процедуры, то перед этой директивой.
// Проверяет, что все поля формы заполнены корректно… // … &НаСервере Процедура ДанныеКорректны(Данные, Отказ)
Структура описания процедуры
Описание
- Содержит текст назначения процедуры.
- Не должно совпадать с именем процедуры.
- Начинается с глагола («Проверяет», «Сравнивает», «Создает», «Сохраняет», «Заполняет» и т.п.).
// Создает структуру со свойствами… // Заполняет таблицу данными… // Проверяет, что цена выше средней…
Допускается указывать описание в несколько строк:
// Создает прокси на основе определения веб-сервиса и связывает // его с точкой подключения веб-сервиса. // В дополнении к платформенному конструктору Новый WSПрокси: // - включает в себя вызов конструктора WSОпределения; // - на время сеанса кэширует файл WSDL для оптимизации частых обращений к веб-сервису; // - не требует явного указания ИнтернетПрокси (он подставляется автоматически, если настроен); // - выполняет быструю проверку доступности веб-сервиса с помощью операции Ping. // ...
Не рекомендуется использовать избыточные слова типа «Процедура» или имя самой процедуры, от удаления из текста описания которых смысл никак не меняется.
Параметры
Если параметры процедуры указаны, то в комментарии к процедуре описываются все параметры. Имя параметра должно быть таким, чтобы было понятно его назначение.
Каждый параметр описывается отдельной строкой в формате «// Имя – Тип – ТекстовоеОписание», где:
- Имя — название параметра (обязательно).
- Тип — тип данных (обязательно), например: Строка, Число, Булево, Массив, Структура, ТаблицаЗначений и т.д.
- ТекстовоеОписание — текстовое описание (заполняется в случае, когда имени недостаточно, и требуется указать дополнительную информацию, а также привести пример с ожидаемым значением параметра).
// Параметры: // СрокОплаты – Дата – срок выплаты зарплаты // Сотрудник – СправочникСсылка.Сотрудники – ссылка на сотрудника, по которому рассчитывается зарплата // СуммаОплаты – Число – рассчитанная сумма оплаты по сотруднику
Также в качестве описания параметра может быть указана ссылка на функцию-конструктор.
// ПараметрыУказанияСерий - см. НоменклатураКлиентСервер.ПараметрыУказанияСерий // СведенияОбОбновлении - Массив из см. ОбновлениеИнформационнойБазы.ПараметрыОбновления // СведенияОРегионе – СтрокаТаблицыЗначений: см. РегистрыСведений.АдресныеОбъекты.КлассификаторСубъектовРФ // КлючОбъекта - Строка - см. синтакс-помощник платформы.
Ещё примеры:
------------------------------------------------------------------------------------------------------- // Параметры: // Реквизиты - Строка - имена реквизитов, перечисленные через запятую. // Например, "Код, Наименование, Родитель". // - Структура, ФиксированнаяСтруктура - в качестве ключа передается // псевдоним поля для возвращаемой структуры с результатом, // а в качестве значения (опционально) фактическое имя поля в таблице. // Если значение не определено, то имя поля берется из ключа. // - Массив Из Строка, ФиксированныйМассив Из Строка - имена реквизитов. ------------------------------------------------------------------------------------------------------- // Параметры: // Дубли - см. ОбработкаОбъект.ПоискИУдалениеДублей.ГруппыДублей // РеквизитыКомпонент - Массив из см. ВнешниеКомпоненты.РеквизитыКомпоненты ------------------------------------------------------------------------------------------------------- // Устарела. Следует использовать ОбщегоНазначения.РазделениеВключено и // ОбщегоНазначения.ДоступноИспользованиеРазделенныхДанных // ... Функция ИспользованиеРазделителяСеанса() Экспорт
Возвращаемое значение
Для процедуры эта секция отсутствует, так как процедура не возвращает никакого значения.
Пример и Варианты вызова
Содержит пример использования процедуры.
// Пример: // Если РолиДоступны("ИспользованиеРассылокОтчетов,ОтправкаПоПочте") Тогда ...
В отдельных случаях, когда сразу несколько параметров имеют дополнительные типы, то используется секция «Варианты вызова», в которой указываются частые или все возможные варианты вызова процедуры.
// Варианты вызова: // ИзменениеЗапрещено(СправочникОбъект...) - проверить данные в переданном объекте (наборе записей). // ИзменениеЗапрещено(Строка, СправочникСсылка...) - проверить данные, полученные из базы данных // по полному имени объекта метаданных и ссылке (отбору набора записей). // ИзменениеЗапрещено(СправочникОбъект..., СправочникСсылка...) - проверить одновременно // данные в переданном объекте и данные в базе (т.е. "до" и "после" записи в базу, если проверка выполняется // перед записью объекта). //
Примеры описания процедур
Пример описания процедуры без параметров:
// Процедура, определяет пользователя, под которым запущен сеанс и пытается // Найти соответствие ему в справочнике Пользователи. Если соответствие // Не найдено - создается новый элемент. Параметр сеанса ТекущийПользователь // Устанавливается как ссылка на найденный (созданный) элемент справочника. // Процедура ОпределитьТекущегоПользователя() … КонецПроцедуры
Пример описания процедуры с параметрами:
// Процедура обработки подключения внешней компоненты, // если компонента подключена, то создает объект драйвера и вызывает обработку оповещения, // если не удалось подключить, то сообщает пользователю о неудаче // // Параметры: // Результат - Булево, Истина - если компонента подключена, Ложь - не подключена // ДополнительныеПараметры - Структура, содержащая параметры для обработки события // Процедура ПодключениеВнешнейКомпонентыПродолжение(Результат, ДополнительныеПараметры) Экспорт … КонецПроцедуры ------------------------------------------------------------------------------------------------------- // Заполняет форму исходящего письма по шаблону. // // Параметры: // ИсходящееПисьмо - СправочникСсылка.ИсходящееПисьмо - данные формы для типа СправочникСсылка.ИсходящееПисьмо, // расположенные в форме редактора исходящего письма. // Текст - ФорматированныйДокумент - поле редактора текста письма, расположенное в форме // редактора исходящего письма. Процедура ЗаполнитьПисьмоПоШаблону(ИсходящееПисьмо, Текст) Экспорт … КонецПроцедуры ------------------------------------------------------------------------------------------------------- // Установить текст запроса, основную таблицу или динамическое считывание в динамическом списке. // Устанавливать эти свойства следует за один вызов этой процедуры, чтобы не снижалась производительность. // // Параметры: // Список - ТаблицаФормы - элемент формы динамического списка, для которого устанавливаются свойства. // СтруктураПараметров - см. СтруктураСвойствДинамическогоСписка(). // Процедура УстановитьСвойстваДинамическогоСписка(Список, СтруктураПараметров) Экспорт … КонецПроцедуры ------------------------------------------------------------------------------------------------------- // Добавляет описание переименования объекта метаданных при переходе на указанную версию конфигурации. // Добавление выполняется в структуру Итог, которая передается в // процедуру ОбщегоНазначенияПереопределяемый.ПриДобавленииПереименованийОбъектовМетаданных. // // Параметры: // Итог - см. ОбщегоНазначенияПереопределяемый.ПриДобавленииПереименованийОбъектовМетаданных. // ВерсияИБ - Строка - версия конечной конфигурации, при переходе на которую нужно // выполнить переименование, например, "2.1.2.14". // СтароеПолноеИмя - Строка - старое полное имя объекта метаданных, которое нужно переименовать, // например "Подсистема._ДемоПодсистемы". // НовоеПолноеИмя - Строка - новое полное имя объекта метаданных, на которое нужно переименовать, // например "Подсистема._ДемоСервисныеПодсистемы". // ИдентификаторБиблиотеки - Строка - внутренний идентификатор библиотеки, к которой относится ВерсияИБ. // Для основной конфигурации не требуется. // Например, "СтандартныеПодсистемы" - как указано // в ОбновлениеИнформационнойБазыБСП.ПриДобавленииПодсистемы. // Пример: // ОбщегоНазначения.ДобавитьПереименование(Итог, "2.1.2.14", // "Подсистема._ДемоПодсистемы", // "Подсистема._ДемоСервисныеПодсистемы"); // Процедура ДобавитьПереименование(Итог, ВерсияИБ, СтароеПолноеИмя, НовоеПолноеИмя, ИдентификаторБиблиотеки = "") Экспорт … КонецПроцедуры ------------------------------------------------------------------------------------------------------- // Сохраняет несколько настроек в хранилище общих настроек, как метод платформы Сохранить, // объектов СтандартноеХранилищеНастроекМенеджер или ХранилищеНастроекМенеджер.<Имя хранилища>, // но с поддержкой длины ключа настроек более 128 символов путем хеширования части, // которая превышает 96 символов. // Если нет права СохранениеДанныхПользователя, сохранение пропускается без ошибки. // // Параметры: // НесколькоНастроек - Массив - со значениями: // * Значение - Структура - со свойствами: // * Объект - Строка - см. параметр КлючОбъекта в синтакс-помощнике платформы. // * Настройка - Строка - см. параметр КлючНастроек в синтакс-помощнике платформы. // * Значение - Произвольный - см. параметр Настройки в синтакс-помощнике платформы. // // ОбновитьПовторноИспользуемыеЗначения - Булево - выполнить одноименный метод платформы. // Процедура ХранилищеОбщихНастроекСохранитьМассив(НесколькоНастроек, ОбновитьПовторноИспользуемыеЗначения = Ложь) … КонецПроцедуры ------------------------------------------------------------------------------------------------------- // Вызывается перед загрузкой новых настроек. Используется для изменения схемы компоновки. // Например, если схема отчета зависит от ключа варианта или параметров отчета. // Чтобы изменения схемы вступили в силу следует вызывать метод ОтчетыСервер.ПодключитьСхему(). // // Параметры: // Контекст - Произвольный - // Параметры контекста, в котором используется отчет. // Используется для передачи в параметрах метода ОтчетыСервер.ПодключитьСхему(). // КлючСхемы - Строка - // Идентификатор текущей схемы компоновщика настроек. // По умолчанию не заполнен (это означает что компоновщик инициализирован на основании основной схемы). // Используется для оптимизации, чтобы переинициализировать компоновщик как можно реже. // Может не использоваться если переинициализация выполняется безусловно. // КлючВарианта - Строка, Неопределено - // Имя предопределенного или уникальный идентификатор пользовательского варианта отчета. // Неопределено когда вызов для варианта расшифровки или без контекста. // Настройки - НастройкиКомпоновкиДанных, Неопределено - // Настройки варианта отчета, которые будут загружены в компоновщик настроек после его инициализации. // Неопределено когда настройки варианта не надо загружать (уже загружены ранее). // ПользовательскиеНастройки - ПользовательскиеНастройкиКомпоновкиДанных, Неопределено - // Пользовательские настройки, которые будут загружены в компоновщик настроек после его инициализации. // Неопределено когда пользовательские настройки не надо загружать (уже загружены ранее). // // Варианты вызова: // Если КлючСхемы <> "1" Тогда // КлючСхемы = "1"; // СхемаКД = ПолучитьОбщийМакет("МояОбщаяСхемаКомпоновки"); // ОтчетыСервер.ПодключитьСхему(ЭтотОбъект, Контекст, СхемаКД, КлючСхемы); // КонецЕсли; - компоновщик отчета инициализируется на основании схемы из общих макетов. // Если ТипЗнч(НовыеПользовательскиеНастройкиКД) = Тип("ПользовательскиеНастройкиКомпоновкиДанных") Тогда // ПолноеИмяОбъектаМетаданных = ""; // Для Каждого ЭлементКД Из НовыеПользовательскиеНастройкиКД.Элементы Цикл // Если ТипЗнч(ЭлементКД) = Тип("ЗначениеПараметраНастроекКомпоновкиДанных") Тогда // ИмяПараметра = Строка(ЭлементКД.Параметр); // Если ИмяПараметра = "ОбъектМетаданных" Тогда // ПолноеИмяОбъектаМетаданных = ЭлементКД.Значение; // КонецЕсли; // КонецЕсли; // КонецЦикла; // Если КлючСхемы <> ПолноеИмяОбъектаМетаданных Тогда // КлючСхемы = ПолноеИмяОбъектаМетаданных; // СхемаКД = Новый СхемаКомпоновкиДанных; // ОтчетыСервер.ПодключитьСхему(ЭтотОбъект, Контекст, СхемаКД, КлючСхемы); // КонецЕсли; // КонецЕсли; - схема зависит от значения параметра, выведенного в пользовательские настройки отчета. // Процедура ПередЗагрузкойНастроекВКомпоновщик(Контекст, КлючСхемы, КлючВарианта, Настройки, ПользовательскиеНастройки) Экспорт … КонецПроцедуры
Важно отметить требование стандарта к переносу строк: длина строки не должна превышать 120 символов, за исключением случаев, когда перенос невозможен.
Описание процедуры отображается в контекстной подсказке, что позволяет, не открывая саму процедуру, видеть информацию о типе и описании каждого параметра этой процедуры. Такое решение значительно упрощает работу с кодом и повышает его читаемость.
Контекстная подсказка
