Как работает функция в 1с
Обновлено: 07.07.2024
Далее подробнее про функции 1С и процедуры 1С.
Порядок объявления функций в модуле произвольный (то есть можно в тексте процедуры, расположенной в самом начале модуля использовать процедуры, текст которых будет расположен ниже в этом модуле). Аналогично переменным 1С, функции 1С могут быть экспортными.
Функция отличается от процедуры возможностью вернуть результат вычислений, например:
Функция Функция1(Параметр)
Возврат Параметр * 2;
КонецФункции
Переменная1 = Функция1(10);
//Переменная1 будет равна 20
При передаче параметра в процедуру/функцию, он передается «по ссылке». Это значит, что изменяя его внутри процедуры, Вы изменяете его значение, при доступе после окончания функции 1С. Таким образом, предыдущий пример можно написать так:
Процедура Процедура1(Параметр)
Параметр = Параметр * 2;
КонецПроцедуры
Переменная1 = 10;
Процедура1(Переменная1);
Сообщить(Переменная1);
//Результатом будет 20
Чтобы передать внутрь процедуры значение переменной, а не ее саму:
Процедура Процедура1(ЗНАЧ Параметр)
//действия..
КонецПроцедуры
При работе с объектами (справочники, документы) необходимо помнить, что внутри функции 1С/процедуры 1С над ними могут быть выполнены действия.
Если у функции 1С/процедуры 1С несколько параметров, то ненужный можно пропустить (указав запятую, если пропущен параметр в середине), при этом будет передано или Неопределено (см. ниже) или значение по-умолчанию:
Функция Функция1(Параметр1, Параметр2, Параметр3 = "Строковое значение")
//Чтото делаем
КонецФункции
//Вызов функции без некоторых параметров
//параметр2 будет равен Неопределено
//параметр3 будет равен "Строковое значение"
Функция1(10);
//Вызов функции без второго параметра
Функция1(10, , "Значение");
В модуле формы, объекта располагаются обработчики событий. Обработчик можно добавить (назначить) следующими способами:
Описание процедур и функций
Область применения: управляемое приложение, мобильное приложение, обычное приложение.
1. Описание процедур и функций рекомендуется выполнять в виде комментария к ним. Необходимость комментирования отдельных участков кода процедур и функций должна определяться разработчиком исходя из сложности и нестандартности конкретного участка кода.
При разработке на платформе 1С:Предприятие 8.3 текст комментария также выводится в контекстной подсказке процедур, функций и их параметров. Подробнее см. раздел «Контекстная подсказка при вводе текстов модулей» главы 27 «Инструменты разработки» в документации к платформе.
При разработке в 1C:Enterprise Development Tools (EDT) текст комментария также используется для уточнения типизации параметров и возвращаемого значения процедур и функций, и тем самым помогает выявлять ошибки кодирования на этапе разработки.
2. Обязательного комментирования требуют процедуры и функции входящие в программный интерфейс модулей - такие процедуры и функции предназначены для использования в других функциональных подсистемах (или в других приложениях), за которые могут отвечать другие разработчики, поэтому они должны быть хорошо документированы.
3. Прочие процедуры и функции (в том числе обработчики событий модулей форм, объектов, наборов записей, менеджеров значений и т.п.) рекомендуется комментировать, если требуется пояснить назначение процедуры (функции) или особенности её работы. Также рекомендуется описывать причины невыполнения некоторых действий, если они кажутся неочевидными для данной процедуры или функции.
Но если процедура (функция) не сложна для понимания и ее назначение и порядок работы следуют из ее названия и имен формальных параметров, комментарий допускается не писать.
4. Следует избегать комментариев, не дающих дополнительных пояснений о работе не-экспортной процедуры (функции).
Например, неправильно:
В этих примерах комментарии избыточны, так как из названий процедур очевидно, что это обработчики событий. А с их описанием и назначением параметров можно ознакомиться в синтакс-помощнике.
Этот комментарий не дает никакой дополнительной информации о функции.
5. Комментарий размещается перед объявлением процедуры (функции) и имеет следующий вид.
5.1. Секция "Описание" (англ. "Description" ) содержит описание назначения процедуры (функции), достаточное для понимания сценариев ее использования без просмотра ее исходного кода. Также может содержать краткое описание принципов работы и перекрестные ссылки на связанные процедуры и функции.
Может быть единственной секцией для процедур без параметров. Описание не должно совпадать с именем процедуры (функции). Для процедур и функций секция должна начинаться с глагола. Для функций это, как правило: «Возвращает…». В тех случаях, когда возвращаемый результат является не основным в работе функции, – то с основного действия, например: «Проверяет…», «Сравнивает…», «Вычисляет…» и т.п. Не рекомендуется начинать описание с избыточных слов «Процедура. », «Функция. », а также с имени самой процедуры (функции), от удаления которых смысл не меняется.
5.2. Секция "Параметры" (англ. "Parameters" ) описывает параметры процедуры (функции). Если их нет, секция пропускается. Предваряется строкой "Параметры:", затем с новой строки размещаются описания всех параметров.
5.2.1. Описание параметра начинается с новой строки, далее имя параметра, затем дефис и список типов (*), далее дефис и текстовое описание параметра.
Имя параметра необходимо стремиться выбирать таким образом, чтобы его назначение было понятно в контексте функции без дополнительных пояснений
Описание типа является обязательным. Тип может быть описан явно, при этом может быть указан или один тип или список типов. Под «списком типов» подразумеваются имена типов, разделенные запятыми. Имя типа может быть простым (в одно слово) или составным - в два слова, разделенных точкой.
Например: Строка, Структура, Произвольный, СправочникСсылка.Сотрудники .
В качестве типов значений следует использовать только существующие в платформе типы, а также специальные типы, предусмотренные в EDT: ОпределяемыйТип.<Имя> , СправочникСсылка , ОбъектМетаданныхОтчет , РасширениеДекорацииФормыДляНадписи и т.п.
Текстовое описание параметра рекомендуется заполнять в том случае, когда только имени параметра в контексте функции не достаточно для понимания его назначения, либо требуется дать дополнительную информацию о типе, поясняющие назначение параметра, а также может приводиться наглядный пример с ожидаемым значением параметра.
// Проверяет, что переданные адреса включены в задачу. Если проверка не проходит – генерируется исключение.
//
// Параметры:
// Адреса - Строка - строка, содержащая электронные адреса
// ЗадачаИсполнителя - ЗадачаСсылка.ЗадачаИсполнителя – проверяемая задача
//
Процедура ПроверитьАдресаЗадачи( Адреса, ЗадачаИсполнителя )
В данном примере текстовое описание для параметра «Адреса» нужно чтобы
- указать правило передачи нескольких адресов (через зяпятую);
- привести пример.
Текстовое описание для параметра ЗадачаИсполнителя не нужно.
5.2.2. Для параметров типа Структура и ТаблицаЗначений также задается описание их свойств и колонок, которые начинаются с новой строки и предваряются символом *.
Например:
При этом текстовое описание свойства (колонки) рекомендуется заполнять в том случае, когда только имени свойства в контексте параметра не достаточно для понимания назначения свойства или требуется дать дополнительную информацию о типе.
5.2.3. Для параметров типа Массив следует указывать тип элементов с помощью ключевого слова "из" (англ. "of" ):
В описании массивов, структур и таблиц значений могут быть вложенные описания, при этом перед именами вложенных свойств число звездочек увеличивается: для первого уровня вложенности 2 звездочки, для второго 3 и т.д.
5.2.4. Также для параметра типа СтрокаТаблицыЗначений ( СтрокаДереваЗначений ) возможно задать состав свойств, соответствующий колонкам его таблицы-владельца (дерева-владельца):
Например:
// СведенияОРегионе – СтрокаТаблицыЗначений: см. РегистрыСведений.АдресныеОбъекты.КлассификаторСубъектовРФ
где КлассификаторСубъектовРФ - экспортная функция модуля менедежра регистра сведения АдресныеОбъекты, которая возвращает таблицу значений.
5.2.5. Также для каждого параметра можно задать одно или несколько дополнительных описаний типов параметра. Каждое дополнительное описание начинается с новой строки, затем обязательный дефис, далее список типов параметра далее дефис и текстовое описание.
Например:
5.2.6. Описание также могут быть заданы с помощью ссылки на функцию-конструктор в формате "см. ПутьКФункции" (англ "see MethodPath" ).
Например:
// ПараметрыУказанияСерий - см. НоменклатураКлиентСервер.ПараметрыУказанияСерий
// Дубли - см. ОбработкаОбъект.ПоискИУдалениеДублей.ГруппыДублей
// РеквизитыКомпонент - Массив из см. ВнешниеКомпоненты.РеквизитыКомпоненты
При разработке кода, обращающегося к реквизитам конкретного объекта метаданных или формы, можно ссылаться на типы реквизитов этого объекта (формы):
Также в редких случаях, когда подходящей функции-конструктора не существует и ее невозможно создать, допустимо указывать ссылку на другую процедуру (при полном совпадении параметров) или на параметр другой процедуры или функции, например:
// См. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту
//
Процедура ПриОпределенииКомандПодключенныхКОбъекту(НастройкиФормы, Источники, ПодключенныеОтчетыИОбработки, Команды) Экспорт
// Параметры:
// НастройкиФормы - см. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту.НастройкиФормы
// Источники - см. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту.Источники
// ПодключенныеОтчетыИОбработки - см. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту.ПодключенныеОтчетыИОбработки
// Команды - см. ПодключаемыеКомандыПереопределяемый.ПриОпределенииКомандПодключенныхКОбъекту.Команды
//
Процедура ПриОпределенииКомандПодключенныхКОбъекту(НастройкиФормы, Источники, ПодключенныеОтчетыИОбработки, Команды) Экспорт
5.3. Секция "Возвращаемое значение" (англ. "Returns" ) описывает тип и содержание возвращаемого значения функции. Для процедур эта секция отсутствует. Предваряется строкой "Возвращаемое значение:". Затем с новой строки тип возвращаемого значения, дефис и текст описания. При использовании возвращаемого значения составного типа следует каждый тип писать с новой строки и с дефиса. Например:
Текстовое описание возвращаемого значения рекомендуется заполнять в том случае, когда только одного описания функции не достаточно, либо требуется дать дополнительную информацию о типе, например, о составе свойств или колонок возвращаемого значения. Также может быть приведен пример с ожидаемым значением возвращаемого значения, либо сквозной пример размещается в секции "Пример" ниже.
Для возвращаемых значений также действуют требования п.5.2.2 и 5.2.3.
5.4. Секция "Пример" (англ. "Example" ) содержит пример использования процедуры, или функции. Предваряется строкой "Пример:". Далее с новой строки пример использования. Имя процедуры (функции) следует писать вместе с именем общего модуля, в котором она расположена. Из примера должно быть понятно, что передается на входе и что возвращается на выходе.
Например, неправильно:
5.4.1. В переопределяемых модулях в секции "Пример" следует размещать пример реализации переопределяемой процедуры, а не пример ее вызова. Например, для процедуры ПриОпределенииОбщихПараметровБазовойФункциональности(ОбщиеПараметры):
5.5. В редких случаях, когда сразу несколько параметров имеют дополнительные типы, рекомендуется добавить секцию "Варианты вызова" (англ. "Сall options" ), в которой дать описания наиболее частых или всех возможных вариантов вызова функции с различными комбинациями типов параметров. Секция начинается фразой "Варианты вызова:" с новой строки, затем идут описания вариантов, каждое начинается с новой строки. Каждый вариант вызова представляется в виде имени функции со списком типов, перечисленных через запятую в круглых скобках, затем следует дефис и текстовое описание варианта.
5.6. В любом месте документирующего комментария можно добавить переход к другим объектам конфигурации, процедурам и функциям (в частности, для перехода к функциям-конструкторам структур). При использовании 1C:Enterprise Development Tools среда оформит такие переходы в виде гиперссылки.
Например:
5.7. В случаях когда возникает необходимость отметить процедуру (функцию) как устаревшую, в первой строке ее описания размещается слово "Устарела" (англ. "Deprecated" )..
Например:
6. Если требуется прокомментировать процедуру или функцию с директивой компиляции, то вначале следует размещать комментарий, а затем -
директиву компиляции. Например:
Такой стиль размещения комментария позволяет в первую очередь обращать внимание на определение функции и директиву компиляции, а потом - на комментарий, который может занимать достаточно большое количество строк.
7. Код процедур и функций должен отделяться друг от друга в тексте модуля пустыми строками.
Примеры описания процедур и функций
Пример описания функции с одним параметром:
Пример описания процедуры без параметров:
Для автоматического упорядочивания комментариев к процедурам или функциям с директивами компиляции можно воспользоваться приложенной обработкой ФорматированиеДирективКомпиляции.epf .
Параметры процедур и функций
Область применения: управляемое приложение, мобильное приложение, обычное приложение.
1. При объявлении формальных параметров процедур и функций (далее по тексту: функций) необходимо придерживаться общих правил образования имен переменных. В частности, имена параметров следует образовывать от терминов предметной области таким образом, чтобы из имени параметра было понятно его назначение.
2. Не следует использовать вместо параметров функций другие средства конфигурирования (переменные модулей, реквизиты формы и т.п.)
3. Параметры в функции должны идти в логической последовательности. Рекомендуется располагать параметры по принципу от общего к частному.
Например, неправильно:
правильно сначала расположить основные параметры ДокументОбъект и Форма :
4. Необязательные параметры (параметры со значениями по умолчанию) должны располагаться после обязательных параметров (без значений по умолчанию).
Например:
5. Не рекомендуется объявлять в функциях много параметров (нужно ориентироваться на количество не более семи параметров), при этом не должно быть много параметров со значениями по умолчанию (нужно ориентироваться на количество не более трех таких параметров). В противном случае, читаемость вызывающего кода сильно снижается. Например, можно легко ошибиться в количестве запятых при передаче необязательных параметров.
При необходимости передавать в функцию большое число параметров рекомендуется:
- группировать однотипные параметры в один или несколько составных параметров типа Структура . Например, в структуры могут быть объединены параметры, описывающие состав и значения полей некоторого объекта ( ДанныеЗаполнения , ПараметрыПроведения, ДанныеФайла и т.п.);
- либо полностью пересмотреть логику работы функции, например, разделив ее на несколько разных, более простых функций.
Правильно пересмотреть логику работы функций, оставив в ней только один ключевой параметр ИмяПоля :
Другой пример. Неправильно:
Правильно сгруппировать параметры, описывающие значения реквизитов номенклатуры, в структуру ЗначенияРеквизитов :
6. При вызове функций необходимо избегать громоздких конструкций, которые приводят к снижению читаемости кода, увеличивают вероятность ошибок и затрудняют отладку.
В частности:
6.1. Не рекомендуется при передаче параметров в одну функцию применять вложенные вызовы других функций.
Неправильно:
Правильно разбивать такие вызовы на отдельные операторы с помощью вспомогательных локальных переменных:
В то же время, если код с вложенными вызовами получается компактным (не требует переноса выражений) и легко читаемым, то вложенные вызовы допустимы.
Например:
6.2. Также не рекомендуется при вызове функций использовать вложенный конструктор структуры: Новый Структура(. ) . Вложенное объявление структуры допустимо только в тех случаях, когда количество ее свойств небольшое (нужно ориентироваться на количество свойств не более трех).
7. При вызове функций не следует пропускать обязательные параметры. В противном случае, в параметр будет передано значение Неопределено , на которое функция может быть не рассчитана. Если же значение Неопределено является допустимым, то нужно или его передавать в функцию явно, или сделать этот параметр необязательным со значением по умолчанию Неопределено .
&НаКлиенте
Функция Округление1 ( ПараметрЧисло , ПараметрЗнОкр )
Возврат Окр ( ПараметрЧисло , ПараметрЗнОкр ); //3.1415926535, 2
&НаКлиенте
Процедура ИсполняемаяПроцедура1 ( Команда )
ТекущееЧисло = 3.1415926535 ;
КолЗнОкр = 2 ;
ОкругленноеЧисло = Округление1 ( ТекущееЧисло , КолЗнОкр );
Сообщить ( ОкругленноеЧисло ); // 3.14
Сообщить ( ПараметрЧисло ); // 2020
Сообщить ( ПараметрДата ); // Неопределено
Сообщить ( ПараметрСтрока ); // "Строковое значение"
&НаКлиенте
Процедура ИсполняемаяПроцедура2 ( Команда )
&НаКлиенте
Процедура ИзменениеПараметра3 ( ПараметрСсылка )
// Изменение значения внутри и снаружи
ПараметрСсылка = 2020 ;
&НаКлиенте
Процедура ИсполняемаяПроцедура3 ( Команда )
ГодЗаписи = 2019 ;
Сообщить ( ГодЗаписи ); // ГодЗаписи = 2019
ИзменениеПараметра3 ( ГодЗаписи );
Сообщить ( ГодЗаписи ); // ГодЗаписи = 2020
&НаКлиенте
Процедура ИзменениеПараметра4 (Знач ПараметрЗначение )
// Изменение значения только внутри процедуры
ПараметрЗначение = 2020 ;
&НаКлиенте
Процедура ИсполняемаяПроцедура4 ( Команда )
ГодЗаписи = 2019 ;
Сообщить ( ГодЗаписи ); // ГодЗаписи = 2019
// Только для простых типов (строка, число, дата), сложные объекты всё равно будут переданы в виде ссылки
ИзменениеПараметра4 ( ГодЗаписи );
Сообщить ( ГодЗаписи ); // ГодЗаписи = 2019 (остался прежним)
&НаКлиенте
Процедура ИзменениеПараметра5 ( ПараметрМассив )
// Изменение первого элемента массива
ПараметрМассив [ 0 ] = 2021 ;
// ПараметрМассив = 2021 и 2020
&НаКлиенте
Процедура ИсполняемаяПроцедура5 ( Команда )
Года = Новый Массив ();
Года . Добавить ( 2019 );
Года . Добавить ( 2020 );
// Создание копии массива через список значений
КопияГода = Новый СписокЗначений ;
КопияГода . ЗагрузитьЗначения ( Года );
КопияГода = КопияГода . ВыгрузитьЗначения ();
// Вызов процедуры, меняющую переданный массив (копия: Года)
ИзменениеПараметра5 ( КопияГода );
// После вызова процедуры в массиве Года по прежнему = 2019 и 2020
Читайте также: