Описание процедур и функций. Описание процедур и функций 1с функция с необязательными переменными

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

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

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

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

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

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

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

Этот комментарий не дает никакой дополнительной информации о функции.

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

5.1. Секция "Описание" содержит словесное краткое описание назначения и/или принципов работы процедуры(функции). Может быть единственной секцией для процедур без параметров.

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

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

// Параметры:

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

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

5.3. Секция "Возвращаемое значение" описывает тип и содержание возвращаемого значения функции. Для процедур эта секция отсутствует. Предваряется строкой " Возвращаемое значение: ". Затем с новой строки список типов (*), далее дефис и текст.
Например:

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

5.4. Секция "Пример" содержит пример использования процедуры, или функции. Предваряется строкой "Пример:". Далее с новой строки пример использования.

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

При разработке на платформе 1С:Предприятие 8.3 текст комментария также выводится в контекстной подсказке процедур, функций и их параметров. Подробнее см. раздел «Контекстная подсказка при вводе текстов модулей» главы 26 «Инструменты разработки» в документации к платформе.

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

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

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

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

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

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

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

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

Автоупорядочивание комментариев к процедурам или функциям с директивами компиляции

Для автоматического упорядочивания комментариев к процедурам или функциям с директивами компиляции можно воспользоваться приложенной обработкой ФорматированиеДирективКомпиляции.epf . Для этого необходимо:

1. Выгрузить модули конфигурации (команда меню Конфигурация -> Выгрузить файлы конфигурации...)
2. Открыть обработку в режиме 1С:Предприятие и указать каталог, в который были выгружены модули - далее нажать кнопку "Форматировать"
3. Загрузить модули в конфигурацию (команда меню Конфигурация -> Загрузить файлы конфигурации...)

Нас находят: пример оглашения и описания процедуры без параметров , параметры процедуры ПередЗаписью() , процдура для использованияконкретной роли 1с, Как поммотреть где используется процедура в 1с, Какие наименования функций или процедур нужно исправить?, разбираться и читать в коде 1с процедура и функция, 1с 77 описание функций, прокомментировать код процедуры материалы количество при изменении, процедуры и функции в 1с, 1с документы процедуры и функции

Описание:

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

При выполнении оператора Возврат процедура заканчивается и возвращает управление в точку вызова. Если в тексте процедуры не встретился оператор Возврат , то после выполнения последнего исполняемого оператора происходит выполнение неявного оператора Возврат . Конец программной секции процедуры определяется по оператору КонецПроцедуры .

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

Синтаксис:

Параметры:

Имя_проц Назначает имя процедуры. Знач Необязательное ключевое слово, которое указывает на то, что следующий за ним параметр передается по значению, то есть изменение значения формального параметра при выполнении процедуры никак не повлияет на фактический параметр, переданный при вызове процедуры. Если это ключевое слово не указано, то параметр процедуры передается по ссылке, то есть изменение внутри процедуры значения формального параметра приведет к изменению значения соответствующего фактического параметра. Парам1 , ..., ПарамN Необязательный список формальных параметров, разделяемых запятыми. Значения формальных параметров должны соответствовать значениям передаваемых при вызове процедуры фактических параметров. В этом списке определяются имена каждого из параметров так, как они используются в тексте процедуры. Список формальных параметров может быть пуст. Экспорт Необязательное ключевое слово, которое указывает на то, что данная процедура является доступной из других программных модулей. Объявляются локальные переменные, на которые можно ссылаться только в рамках этой процедуры. // Операторы Исполняемые операторы процедуры. Возврат Необязательное ключевое слово, которое завершает выполнение процедуры и осуществляет возврат в точку программы, из которой было обращение к процедуре. Использование данного оператора в процедуре не обязательно. КонецПроцедуры Обязательное ключевое слово, обозначающее конец исходного текста процедуры, завершение выполнения процедуры. Возврат в точку, из которой было обращение к процедуре.

Функция

Описание:

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

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

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

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

Синтаксис:

Параметры:

Имя_функции Назначает имя функции. Знач Необязательное ключевое слово, которое указывает на то, что следующий за ним параметр передается по значению, т.е. изменение значения формального параметра при выполнении функции никак не повлияет на фактический параметр, переданный при вызове функции. Если это ключевое слово не указано, то параметр функции передается по ссылке, то есть изменение внутри функции значения формального параметра приведет к изменению значения соответствующего фактического параметра. Парам1 , ..., ПарамN Необязательный список формальных параметров, разделяемых запятыми. Значения формальных параметров должны соответствовать значениям передаваемых при вызове функции фактических параметров. В этом списке определяются имена каждого из параметров так, как они используются в тексте функции. Список формальных параметров может быть пуст. = ДефЗнач Необязательная установка значения параметра по умолчанию. Параметры с установленными значениями по умолчанию можно располагать в любом месте списка формальных параметров. Экспорт Необязательное ключевое слово, которое указывает на то, что данная функция является доступной из других программных модулей. // Объявления локальных переменных Объявляются локальные переменные, на которые можно ссылаться только в рамках этой функции. // Операторы Исполняемые операторы функции. Возврат Возвращаемое значение Ключевое слово, которое завершает выполнение функции и возвращает указанное значение в выражение, в котором используется функция. В качестве возвращаемого значения может выступать выражение или переменная, значение которого содержит результат обращения к функции. КонецФункции Обязательное ключевое слово, обозначающее конец исходного текста функции.

Функции 1С и процедуры в 1С работают аналогично другим языкам — функция это именованная подпрограмма для вызова из других мест программного кода.

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

Чтобы «выйти» из выполнения функции 1С и процедуры — используют команду «Возврат;». Функция (в отличии от процедуры) «возвращает» результат вычислений, то есть необходимо написать «Возврат ЗНАЧЕНИЕ;». Функции 1С не типизированы, значит могут возвращать значение разных типов, в зависимости от параметров или условий.

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

Функция Функция1(Параметр)
Возврат Параметр * 2;
КонецФункции

Переменная1 = Функция1(10);
//Переменная1 будет равна 20

Параметры функции 1С и процедуры — это ссылки на переменные, существующие в месте вызова. «Ссылка» — значит при изменении значения параметра «внутри» функции 1С, он будет изменен и «снаружи». Чтобы такого не происходило — параметр передают со значением ПЕРЕМ. Однако это не работает со значениями-объектами (списками, таблицами, объектами базы данных), они все-равно будут переданы по ссылке.

При передаче параметра в процедуру/функцию, он передается «по ссылке». Это значит, что изменяя его внутри процедуры, Вы изменяете его значение, при доступе после окончания функции 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С автоматически прописывает список параметров.

Эта статья продолжает цикл статей «Первые шаги в разработке на 1С». В ней будут рассмотрены следующие вопросы:

• Что такое процедуры и функции и когда их нужно использовать?
• В чем отличие процедуры от функции?
• Что такое параметр процедуры (функции) и как его передать?
• В каком случае передавать параметр по ссылке, а в каком по значению?
• Как быстро посмотреть список процедур текущего модуля?

Применимость

Материал полностью актуален для платформы «1С:Предприятие 8» редакций 8.2. и 8.3.

Процедуры и функции

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

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

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

В итоге облегчается сопровождение прикладного решения.

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

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

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

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

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

Процедура или функция начинает описываться со слова Процедура (Функция). Далее следует Имя процедуры (функции). После имени обязательно указываются круглые скобки. Внутри скобок могут находиться описываемые параметры.

Данные параметры нужно будет передавать при вызове (при обращении к процедуре). После круглых скобок может стоять слово Экспорт (экспортная функция).

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

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

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

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

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

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

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

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

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

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

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

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

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

Следует сказать, что в некоторые процедуры-обработчики передается такой параметр, как Отказ . Значение данного параметра по умолчанию – Ложь .

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

Порядок следования процедур и функций в модуле 1С:Предприятие 8 значения не имеет. Из любой процедуры (функции) модуля можно вызывать любую другую процедуру или функцию данного модуля.

Чтобы обратиться к списку процедур текущего модуля в панели конфигуратора можно нажать на кнопку в виде лупы с надписью «PROC» или использовать горячие клавиши (Ctrl+Alt+P ).

Откроется диалоговое окно, в котором описаны функции F(x) и процедуры P() . К ним возможно обращаться.

Список может быть отсортирован в алфавитном порядке (для этого устанавливается галочка «Сортировка»).

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

Кроме процедур и функций в списке для разных модулей будут доступны разные стандартные обработчики. При выборе обработчика двойным кликом мыши в модуле создается шаблон соответствующей процедуры (обработчика события).

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

Справа от кнопки с надписью «PROC» располагается поле. В этом поле указано имя текущей процедуры (функции).

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