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

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

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

Синтаксис комментариев во встроенном языке 1С

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

// Комментарий на всю строку
СуммаДокумента = СуммаДокумента + СуммаСтроки; // комментарий в конце строки

Компилятор не поддерживает парные разделители вида / ... /, как в C-подобных языках. Если нужно закомментировать большой фрагмент, каждую строку отмечают символами // — в конфигураторе для этого есть горячие клавиши: выделите блок и нажмите Ctrl+/ (в некоторых раскладках Ctrl+Num+/), чтобы закомментировать или раскомментировать весь блок сразу.

Есть важный нюанс: если внутри строки-комментария стоит символ продолжения или кавычки, они не влияют на компиляцию — комментарий обрывается только переводом строки. Поэтому случайное удаление перевода строки при слиянии может «проглотить» следующую исполняемую строку. Проверяйте такие места после объединения веток хранилища.

// Рассчитываем скидку только для постоянных клиентов,
// временную акцию сюда не включаем (см. задачу № 145)
Если Клиент.Постоянный Тогда
    СуммаСкидки = СуммаДокумента * 0.05;
КонецЕсли;

Комментарии в текстах запросов

Язык запросов 1С имеет собственный синтаксис комментариев, отличный от встроенного языка. Внутри текста запроса используются те же двойные слэши //, но они работают только внутри строки запроса, а не в коде, который этот запрос формирует.

Запрос.Текст =
"ВЫБРАТЬ
|	Продажи.Номенклатура КАК Номенклатура,
|	СУММА(Продажи.Количество) КАК Количество
|ИЗ
|	РегистрНакопления.Продажи КАК Продажи
|ГДЕ
|	Продажи.Период МЕЖДУ &Начало И &Конец // период задаёт пользователь
|СГРУППИРОВАТЬ ПО
|	Продажи.Номенклатура";

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

Описание процедур и функций по стандарту

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

// Рассчитывает сумму скидки по условиям договора.
//
// Параметры:
//  Договор - СправочникСсылка.ДоговорыКонтрагентов - договор покупателя.
//  СуммаДокумента - Число - сумма до применения скидки.
//
// Возвращаемое значение:
//  Число - сумма скидки.
//
Функция РассчитатьСкидку(Договор, СуммаДокумента) Экспорт

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

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

1. 1
   Перед строкой «Функция ... Экспорт» добавьте строку с кратким назначением в форме инфинитива: «Рассчитывает...», «Возвращает...».
2. 2
   Добавьте секцию «Параметры:» и перечислите каждый параметр с типом и пояснением.
3. 3
   Добавьте секцию «Возвращаемое значение:» с типом и смыслом результата.
4. 4
   Откройте другой модуль, начните вводить имя метода и убедитесь, что описание появилось в контекстной подсказке.

Комментарии-заглушки и временное отключение кода

Во время разработки часто требуется временно отключить фрагмент кода. Самый безопасный способ — закомментировать блок через Ctrl+/. Альтернатива — обернуть код в инструкции препроцессора #Если Ложь Тогда ... #КонецЕсли, но этот приём хуже читается и легко забывается в конфигурации.

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

Для пометок «доделать позже» используйте единообразные метки, например // TODO: с текстом задачи. Их легко найти глобальным поиском по модулю или по всей конфигурации (Ctrl+Shift+F), а при наличии EDT — через встроенный список задач.

Что стоит и чего не стоит комментировать

Комментируйте причины решений, неочевидные ограничения и обходные пути: почему выбран именно такой алгоритм, какая особенность учёта заставила отказаться от типового подхода, на какие данные опирается условие. Также обязательны пояснения к «магическим» числам и датам — если в коде стоит константа, должно быть ясно, откуда она взялась.

Не комментируйте то, что очевидно из имён переменных и методов. Строка НайденнаяСтрока = ТаблицаТоваров.Найти(Артикул, "Артикул"); // ищем строку по артикулу не добавляет информации. Если код настолько запутан, что требует построчных пояснений, правильнее переименовать переменные и разбить метод, а не закрывать проблему комментариями.

При доработке типовых конфигураций помечайте вставки и изменения согласованным маркером, например // Доработка: начало и // Доработка: конец с указанием причины. Это резко упрощает обновление: при сравнении и объединении сразу видно, какие фрагменты — ваши, и их не «затрёт» типовой код без внимания.

Проверка качества комментариев при ревью

При приёмке доработки проверяйте комментарии так же, как код. Полезный приём — прочитать модуль, глядя только на комментарии и сигнатуры методов: если по ним можно восстановить логику работы и назначение каждого экспортного метода, описание достаточное. Если картина не складывается, описания нужно дополнить.

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

Частые вопросы