Использование соглашения по оформлению кода при написании кода

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

Обозначения в статье по соглашениям при написании кода:

✅ – разрешено

⚠️ – допустимые исключения

❌ – запрет на использование

✅ Пишутся на русском языке

⚠️ Рекомендуется на английском языке задавать:

• имена и параметры веб-сервисов (пример на рисунке),

• различные идентификаторы сторонних информационных систем, например, «внешних» структур данных.

❌ Не используйте:

• букву «ё»,
• неразрывные пробелы,
• знак минус «-» в других кодировках (короткое, длинное тире и т. п.).

❌ Удаляйте:

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

✅ Оформляются по принципу «один оператор в одной строке».

⚠️ Несколько операторов только для «однотипных» операторов присваивания (пример на рисунке).

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

Стандартный размер табуляции – 4 символа. Проверка настроек табуляции в конфигураторе осуществляется через «Сервис – Параметры».

⚠️ С крайней левой позиции только:

• операторы Процедура, КонецПроцедуры, Функция, КонецФункции;
• заголовки (описания) процедур и функций;
• объявление переменных модуля; 
• код вне процедур и функций (с учетом синтаксического отступа);
• директивы компилятора &НаКлиенте, &НаСервере и т. д. и аннотации &Перед, &После и другие;
• инструкции препроцессора (в т. ч. #Область и #КонецОбласти).

❌ Текст внутри процедур НачатьТранзакцию и ЗафиксироватьТранзакцию не сдвигается, поскольку они не являются операторными скобками.

✅ Перенос строки при длине строки более 120 символов.

⚠️ Перенос строки невозможен, если, например, в коде определена длинная строковая константа, которая выводится без переносов в окно сообщений с помощью объекта СообщениеПользователю.

✅ Комментарии должны быть достаточно понятными, чтобы пояснять работу модуля или комментируемого оператора.

⚠️ Тексты комментариев должны составляться по правилам русского языка, в деловом стиле, быть эмоционально сдержанными и не содержать слов, не относящихся к функциональности программы.

✅ В конце строки пишутся небольшие комментарии. Пример небольшого комментария в тексте модуля на рисунке.

✅ Перед комментируемым кодом в отдельной строке пишутся большие комментарии или комментарии к фрагменту кода. 

Текст выравнивается по левой границе комментируемого фрагмента. Между символами комментария «//» и текстом комментария должен быть пробел.

✅ Тексты больших процедур и функций можно разбивать на отдельные сворачиваемые области.

✅ Разделы в программном модуле:

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

⚠️ Требование о разделении кода модуля на разделы призвано повысить читаемость кода и упростить внесение изменений в код разными авторами (разработчиками) как при коллективной разработке, так и при доработке прикладных решений на конкретных внедрениях.

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

✅ Разделы и подразделы оформляются в виде областей.

Программный интерфейс 

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

Например, процедуры заполнения табличной части документа, которые вызываются из обработки заполнения в модуле объекта и из формы документа в обработчике команды формы, не являются программным интерфейсом модуля объекта, поскольку вызываются только в самом модуле и из форм этого же объекта. Их следует размещать в разделе «Служебные процедуры и функции».

Служебный программный интерфейс

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

Служебные процедуры и функции

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

Обработчики событий

Содержит обработчики событий модуля объекта (ПриЗаписи, ПриПроведении и др.) или процедуру-обработчик команды ОбработкаКоманды.

Описание переменных

Содержит имена переменных и их использование, с комментариями, размещенными в той же строке.

Инициализация

Содержит операторы, инициализирующие переменные модуля или объект (форму).

✅ Распорядок разделов в модулях

Распорядок разделов в модулях представлен на рисунках.

Распорядок разделов для общего модуля:

Распорядок разделов для модуля объекта, менеджера, набора записей:

Распорядок разделов для модуля формы:

Распорядок разделов для модуля команды:

❌ В модуле не должно быть пустых областей.

✅ Заголовок модуля содержит краткое описание и условия применения и располагается в самом начале модуля.

✅ Рекомендуется располагать обработчики событий в порядке их следования в описании встроенного языка.

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

✅ Выбор имен процедур и функций важен для повышения читаемости кода.

✅ Хорошо выбранное имя процедуры и параметры могут избавить от необходимости дополнительного описания.

⚠️ Сложности в выборе имени процедуры и параметров могут указывать на неправильную архитектуру программного кода.

✅ «Самодокументирующееся» придуманное имя указывает на правильно спроектированную процедур.

✅ Имена процедур, функций и формальных параметров должны быть образованы от терминов предметной области.

⚠️ Важно, чтобы имена были «говорящими» и документировали сами себя

❌ Неправильно использовать длинные и непонятные имена функций.

Примеры правильных имен: 

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

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

✅ Предлоги и местоимения из одной буквы также должны быть написаны прописными буквами.

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

Примеры неправильных названий:

Примеры правильных названий:

⚠️ Исключение составляют случаи, когда описание типа возвращаемого значения необходимо для ясности назначения процедуры или функции.

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

Пример неправильного имени процедуры:

Пример правильного имени процедуры:

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

Пример неправильного имени функции:

Пример правильного имени функции:

✅ Рекомендуется использовать слово «Новый» в имени функции, если она создает объект.

Пример неправильного описания имени функции при создании объекта:

Пример правильного описания имени функции при создании объекта.

✅ Для функций, проверяющих условия, рекомендуется использовать слова «Это» или причастия. 

Пример неправильного описания имени функции при проверке условия:

Пример правильного описания имени функции при проверке условия:

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

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

Пример правильного описания имени функции:

✅ Рекомендуется комментировать процедуры и функции для ясности и выявления ошибок кодирования.

⚠️ Разработчики должны определить необходимость комментирования на основе сложности и нестандартности кода.

✅ Текст комментария выводится в контекстной подсказке процедур, функций и их параметров в платформе «1С:Предприятие 8.3». 

✅ В 1C:Enterprise Development Tools (EDT) текст комментария используется для уточнения типизации параметров и возвращаемого значения процедур и функций.

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

✅ Рекомендуется комментировать процедуры и функции для пояснения назначения и особенностей работы.

✅ Описывать причины невыполнения действий, если они кажутся неочевидными.

⚠️ Если процедура понятна и следует из названия и имен формальных параметров, комментарий может быть не написан.

❌ Избегать комментариев, не дающих дополнительных пояснений о работе неэкспортных процедур.

Пример избыточного комментария, так как из названий процедур очевидно, что это обработчики событий:

Пример комментария, который не несет никакой дополнительной информации о данной функции:

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

Секция «Описание» (англ. «Description»)  

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

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

❌ Описание не должно совпадать с именем процедуры (функции).

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

⚠️ Для процедур и функций секция должна начинаться с глагола, например, «Возвращает...» для функций.

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

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

Секция «Параметры» (англ. «Parameters»)

Описывает параметры процедуры (функции).

❌ Если нет параметров, секция пропускается.

✅ Описание параметра начинается с новой строки, затем указывается имя параметра, дефис и список типов.

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

⚠️ Описание типа является обязательным.

✅ Тип может быть описан явно или указан список типов.

⚠️ В качестве типов значений следует использовать только существующие в платформе типы и специальные типы, предусмотренные в EDT. 

Пример неправильного комментария при описании типов:

Пример правильного комментария при описании типов:

✅ Текстовое описание параметра рекомендуется использовать, когда имени параметра недостаточно для понимания его назначения.

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

Пример неправильного текстового описания:

Пример правильного текстового описания:

В примере для параметра «Адреса» необходимо указать правила передачи нескольких адресов через запятую и предоставить пример. Текстовое описание для параметра «ЗадачаИсполнителя» не требуется.

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

Пример правильного текстового описания:

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

✅ Для параметров типа Массив следует указывать тип элементов с помощью ключевого слова «из».

⚠️ Допускается не указывать тип элементов массивов только в методах, которые работают с массивами универсальным образом.

✅ Для параметра типа СтрокаТаблицыЗначений (СтрокаДереваЗначений) возможно задать состав свойств, соответствующий колонкам его таблицы-владельца (дерева-владельца).

✅ Для каждого параметра можно задать одно или несколько дополнительных описаний типов параметра.

✅ Описание параметров может быть задано с помощью ссылки на функцию-конструктор «см. ОбщегоНазначения. ЕстьРеквизитИлиСвойствоОбъекта».

✅ При разработке кода можно ссылаться на типы реквизитов объекта метаданных или формы, если код обращается к реквизитам конкретного объекта метаданных или формы.

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

Секция «Возвращаемое значение» (англ. «Returns»)

Описывает тип и содержание возвращаемого значения функции.

❌ Для процедур эта секция отсутствует.

⚠️ Возвращаемое значение составного типа следует писать с новой строки и с дефиса. 

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

Секция «Пример» (англ. «Example»)

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

✅ Пример начинается со строки «Пример:».

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

⚠️ Из примера должно быть понятно, что передается на входе и что возвращается на выходе.

❌ Неправильно указывать только пример, необходимо указать имя модуля и процедуру.

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

Секция «Варианты вызова» (англ. «Сall options»)

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

✅ В документирующем комментарии можно добавить переходы к другим объектам конфигурации, процедурам и функциям.

⚠️ 1C:Enterprise Development Tools оформляет такие переходы в виде гиперссылки.

Секция «Устарела» (англ. «Deprecated»)

Используется, когда процедура (функция) считается устаревшей.

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

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

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

✅ При объявлении формальных параметров процедур и функций необходимо придерживаться общих правил образования имен переменных.

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

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

✅ Параметры в функции должны идти в логической последовательности.

✅ Рекомендуется располагать параметры по принципу от общего к частному.

⚠️ Необязательные параметры должны располагаться после обязательных параметров без значений по умолчанию.

⚠️ Рекомендуется не объявлять в функциях много параметров и не использовать много параметров со значениями по умолчанию.

⚠️ Большое количество необязательных параметров и параметров со значениями по умолчанию снижает читаемость кода.

⚠️ Ошибки в количестве запятых при передаче необязательных параметров могут возникнуть при использовании большого количества параметров.

⚠️ Если необходимо использовать большое число параметров:

✅ Рекомендуется группировать однотипные параметры в составные параметры типа Структура;

✅ Структуры могут объединять параметры, описывающие состав и значения полей объекта;

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

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

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

✅ Разбивайте такие вызовы на отдельные операторы с помощью вспомогательных локальных переменных.

✅ Вложенные вызовы допустимы, если код получается компактным (без переноса выражений) и легко читаемым.

❌ Не рекомендуется использовать вложенный конструктор структуры «Новый Структура(..)» при вызове функций.

⚠️ Вложенное объявление структуры допустимо только для небольшого количества свойств (не более трех).

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

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

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

⚠️ Необходимо определить функцию-конструктор параметров, возвращающую структуру-заготовку или пустую таблицу значений с типизированными колонками.

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

✅ Имена свойств структуры соответствуют параметрам вызываемой функции.

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

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

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

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

Пример правильного описания параметра «Таблица значений»:

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

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

⚠️ Во избежание неоднозначности и скрытых ошибок все допустимые параметры вызываемой функции должны быть определены явно в функции-конструкторе параметров.

✅ Имена переменных должны быть образованы от терминов предметной области для ясности назначения.

⚠️ Имена следует образовывать путем удаления пробелов между словами, каждое слово пишется с прописной буквы.

✅ Предлоги и местоимения из одной буквы также пишутся прописными буквами.

Пример правильного образования имен переменных:

❌ Имена переменных не должны начинаться с подчеркивания.

❌ Имена переменных не должны состоять из одного символа. Исключение: счетчики циклов.

⚠️ Переменные, отражающие состояние флага, следует называть так, как пишется истинное значение этого флага.

Пример правильного образования имен переменных, отражающий состояние флага: