Как правильно оформлять комментарии при доработке кода в 1С

← На главную

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

Шаблоны разметки блоков кода с использованием авторских тегов

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

Базовая схема включает указание автора, даты, номера заявки в баг-трекере, а также сохранение исходного кода на период отладки:


//++ ИвановИИ 2024.11.20 Задача №1245
// Добавлен пересчет суммы с учетом скидки партнера
// СуммаДокумента = Итог("Сумма");
СуммаДокумента = ПересчитатьСуммуСоСкидкой(Итог("Сумма"), Партнер);
//-- ИвановИИ 2024.11.20

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

Парные открывающие и закрывающие метки: использование символов //++ и //-- (или //<< и //>>) позволяет быстро переходить между началом и концом доработанного блока, а также настраивать поиск по модулю.
Идентификатор разработчика и дата: фамилия или инициалы автора вместе с датой в формате ГГГГ.ММ.ДД помогают хронологически отслеживать правки и находить ответственного за логику.
Ссылка на задачу или заявку: указание номера инцидента или тикета связывает строку кода с техническим заданием и бизнес-требованиями.
Пояснение сути изменения: краткое описание того, зачем было выполнено вмешательство в исходный алгоритм.
Комментирование исходной строки: старый код временно сохраняется закомментированным, чтобы упростить откат логики в случае выявления ошибок.

Стандарты комментирования вендора и библиотек стандартных подсистем

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

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


// Вставка
Если Не ЗначениеЗаполнено(Организация) Тогда
    Организация = ОсновнаяОрганизация;
КонецЕсли;
// Конец Вставка

Если выполняется замена существующего блока типового алгоритма, оформление выглядит следующим образом:


// Удаление
// Валюта = Шапка.ДоговорКонтрагента.ВалютаВзаиморасчетов;
// Конец Удаления
// Вставка
Валюта = Константы.ВалютаРегламентированногоУчета.Получить();
// Конец Вставка

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

Организация комментариев в шапке модуля и обработок

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

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


////////////////////////////////////////////////////////////////////////////////
// ИСТОРИЯ ИЗМЕНЕНИЙ МОДУЛЯ:
// 2024.10.15 Сидоров А.В. [Задача 432]: Добавлена функция РасчетСкидкиПоАкции()
// 2024.11.02 Иванов И.И. [Задача 510]: Изменен вызов формирования проводок
////////////////////////////////////////////////////////////////////////////////

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

Современная альтернатива: расширения конфигурации и аннотация ИзменениеИКонтроль

Развитие платформы позволяет отказаться от модификации кода основной конфигурации и снятия объектов с полной поддержки. Для переопределения логики используются расширения конфигурации.

Для точечной доработки типовых методов без полной подмены тела процедуры применяется директива аннотации &ИзменениеИКонтроль. Внутри нее платформа предоставляет препроцессорные теги версионирования:


&Вместо("РассчитатьСкидку")
&ИзменениеИКонтроль("РассчитатьСкидку")
Процедура Расш1_РассчитатьСкидку(СтрокаТабличнойЧасти)
    #Удаление
    // Скидка = 0;
    #КонецУдаления
    #Вставка
    Скидка = ПолучитьПерсональнуюСкидку(СтрокаТабличнойЧасти.Номенклатура);
    #КонецВставки
КонецПроцедуры

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

Чистота кода, системы контроля версий и статический анализ

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

Захламление визуального пространства: закомментированные фрагменты кода («мертвый код») затрудняют чтение алгоритма и увеличивают вероятность логических ошибок при чтении программы другими разработчиками.
Ложные срабатывания поиска: глобальный поиск по конфигурации находит вхождения как в работающем коде, так и в закомментированном, создавая лишний информационный шум.
Срабатывание анализаторов качества: современные средства статического анализа кода для платформы 1С расценивают наличие закомментированного исполняемого кода как дефект и технический долг.
Автоматическая история: инструменты систем версионирования позволяют с помощью встроенных команд аннотирования строк увидеть автора любого изменения, точную дату фиксации и номер связанной задачи без единого служебного комментария в тексте модуля.

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