🔥 Горящие вакансии
Все статьи

Как оформить описание процедуры по стандарту 1С

Эту и другие технические статьи написали наши программисты 1С и получили за них премии. Если вы тоже работаете с 1С и любите делиться опытом, приходите разработчиком в Neti

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

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

Инструкции составлены на основе методических материалов проверенного источника — 1С:ИТС.

Общие правила

Описание процедуры выполняется в виде комментария («//…»).

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

Не стоит писать комментарий к процедуре, если он никак не поясняет или никак не дополняет логику работу процедуры.

// Простить и забыть
Процедура УдалитьОбъект()

Между секциями комментария должна быть пустая строка комментария для удобства чтения:

// Заполняет таблицу ценами…
//
// Параметры:
//   ТаблицаТоваров - ТаблицаЗначений – таблица с товарами…
//   ПараметрыЗаполненияЦен - см. ЦенообразованиеСервер.ПараметрыЗаполненияЦен 
//

Описание указывается непосредственно перед самой процедурой, а если указана директива компиляции процедуры, то перед этой директивой.

// Проверяет, что все поля формы заполнены корректно…
// …
&НаСервере
Процедура ДанныеКорректны(Данные, Отказ)

Структура описания процедуры

Описание

  • Содержит текст назначения процедуры.
  • Не должно совпадать с именем процедуры.
  • Начинается с глагола («Проверяет», «Сравнивает», «Создает», «Сохраняет», «Заполняет» и т.п.).
// Создает структуру со свойствами…
// Заполняет таблицу данными…
// Проверяет, что цена выше средней…

Допускается указывать описание в несколько строк:

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

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

Параметры

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

Каждый параметр описывается отдельной строкой в формате «// Имя – Тип – ТекстовоеОписание», где: 

  • Имя — название параметра (обязательно).
  • Тип — тип данных (обязательно), например: Строка, Число, Булево, Массив, Структура, ТаблицаЗначений и т.д.
  • ТекстовоеОписание  — текстовое описание (заполняется в случае, когда имени недостаточно, и требуется указать дополнительную информацию, а также привести пример с ожидаемым значением параметра).
// Параметры:
// СрокОплаты – Дата – срок выплаты зарплаты
// Сотрудник – СправочникСсылка.Сотрудники – ссылка на сотрудника, по которому рассчитывается зарплата
// СуммаОплаты – Число – рассчитанная сумма оплаты по сотруднику

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

// ПараметрыУказанияСерий - см. НоменклатураКлиентСервер.ПараметрыУказанияСерий
// СведенияОбОбновлении  - Массив из см. ОбновлениеИнформационнойБазы.ПараметрыОбновления
// СведенияОРегионе – СтрокаТаблицыЗначений: см. РегистрыСведений.АдресныеОбъекты.КлассификаторСубъектовРФ
//   КлючОбъекта       - Строка           - см. синтакс-помощник платформы.

Ещё примеры:

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

Возвращаемое значение

Для процедуры эта секция отсутствует, так как процедура не возвращает никакого значения.

Пример и Варианты вызова

Содержит пример использования процедуры.

// Пример:
// Если РолиДоступны("ИспользованиеРассылокОтчетов,ОтправкаПоПочте") Тогда ...

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

// Варианты вызова:
//   ИзменениеЗапрещено(СправочникОбъект...)         - проверить данные в переданном объекте (наборе записей).
//   ИзменениеЗапрещено(Строка, СправочникСсылка...) - проверить данные, полученные из базы данных 
//      по полному имени объекта метаданных и ссылке (отбору набора записей).
//   ИзменениеЗапрещено(СправочникОбъект..., СправочникСсылка...) - проверить одновременно 
//      данные в переданном объекте и данные в базе (т.е. "до" и "после" записи в базу, если проверка выполняется
//      перед записью объекта).
//

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

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

// Процедура, определяет пользователя, под которым запущен сеанс и пытается
// Найти соответствие ему в справочнике Пользователи. Если соответствие
// Не найдено - создается новый элемент. Параметр сеанса ТекущийПользователь
// Устанавливается как ссылка на найденный (созданный) элемент справочника.
//
Процедура ОпределитьТекущегоПользователя()КонецПроцедуры

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

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

Важно отметить требование стандарта к переносу строк: длина строки не должна превышать 120 символов, за исключением случаев, когда перенос невозможен.

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

Контекстная подсказка 1С

Контекстная подсказка

Оставить коментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Раз в квартал — дайджест достойный внимания

Вести с полей 1С, кейсы работы с заказчиками и вакансии на удалёнке

Image

Отправить резюме

    Я согласен на обработку персональных данных в соответствии
    со ст. 9 ФЗ № 152-ФЗ «О персональных данных»

    Отправить резюме

      Я согласен на обработку персональных данных в соответствии
      со ст. 9 ФЗ № 152-ФЗ «О персональных данных»

      Pекомендовать друга

        Отправьте контактные данные вашего друга и предупредите его, что мы с ним свяжемся. Когда друг успешно отработает 3 месяца, вы получите 20 000 ₽.


        Выбрать вакансию
        • Ведущий аналитик 1С
        • Программист 1С
        • Консультант-аналитик 1С
        • Проекты для команды специалистов 1С
        • Проекты для специалистов 1С
        • Стажёр-программист 1С
        • Bitrix-разработчик
        Я согласен на обработку персональных данных в соответствии
        со ст. 9 ФЗ № 152-ФЗ «О персональных данных»

        Pекомендовать друга

          Отправьте контактные данные вашего друга и предупредите его, что мы с ним свяжемся. Когда друг успешно отработает 3 месяца, вы получите 20 000 ₽.


          Выбрать вакансию
          • Ведущий аналитик 1С
          • Программист 1С
          • Консультант-аналитик 1С
          • Проекты для команды специалистов 1С
          • Проекты для специалистов 1С
          • Стажёр-программист 1С
          • Bitrix-разработчик
          Я согласен на обработку персональных данных в соответствии
          со ст. 9 ФЗ № 152-ФЗ «О персональных данных»

          Спасибо!

          Мы получили ваше резюме. Менеджер свяжется с вами в течение трех дней

          Горящие вакансии