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

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

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

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

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

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

// Рассчитываем скидку по накопительной программе
СуммаСкидки = СуммаДокумента * ПроцентСкидки / 100; // процент хранится в карточке клиента

Комментарии можно использовать внутри запросов на языке запросов 1С — там синтаксис тот же, двойной слэш. Это удобно для пояснения сложных соединений и условий виртуальных таблиц.

Что комментировать, а что — нет

Главный принцип: комментарий должен отвечать на вопрос «почему», а не «что». Строка Сумма = Сумма + НДС; // прибавляем НДС к сумме бесполезна — код и так это говорит. Полезный комментарий объясняет неочевидное: «НДС добавляем отдельно, потому что для экспортных операций ставка 0% определяется позже по подтверждающим документам».

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

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

Оформление заголовков процедур и функций

В экосистеме 1С принято оформлять экспортные процедуры и функции структурированным заголовком. Такой формат используется в стандартах разработки фирмы «1С» и поддерживается инструментами контроля качества кода. Заголовок размещается перед объявлением процедуры:

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

Такой заголовок включает краткое описание назначения, секцию «Параметры» с типами и смыслом каждого аргумента, а для функций — секцию «Возвращаемое значение». Если процедура вызывается из определённых мест и имеет побочные эффекты (запись в базу, вызов внешних сервисов), это тоже стоит указать.

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

Комментирование доработок типовых конфигураций

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

// {Доработка.Иванов: добавлен контроль остатка по резерву
Если ОстатокСвободный < Количество Тогда
ВызватьИсключение "Недостаточно свободного остатка";
КонецЕсли;
// }Доработка.Иванов

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

Комментарии в запросах и сложных участках

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

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

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

Типичные ошибки при написании комментариев

Отдельная ошибка — описывать в комментарии то, что должно быть выражено кодом. Если приходится писать «здесь магическое число 0,18 — это коэффициент пересчёта», лучше ввести именованную константу с понятным именем, а комментарием указать источник значения.

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

Как проверить качество комментариев в своём модуле

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

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

Контрольные точки

Как проверить результат

Заголовки экспортных процедур и функций

Норма

Есть описание назначения, параметров и возвращаемого значения

Тревожный признак

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

Доработки типового кода

Норма

Все правки заключены в маркеры с указанием причины

Тревожный признак

Изменённые строки без пометок, удалённый типовой код без комментария

Соответствие комментариев коду

Норма

Комментарий описывает текущее поведение кода

Тревожный признак

Комментарий описывает старую версию логики

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

Есть ли в 1С многострочные комментарии?

Нет, блочного синтаксиса вида / ... / во встроенном языке нет. Каждую строку комментария нужно начинать с двойного слэша. В конфигураторе есть команды «Закомментировать» и «Раскомментировать» для выделенного блока, которые автоматически расставляют // на каждой строке.

Замедляют ли комментарии выполнение кода?

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

Нужно ли комментировать каждую процедуру?

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

Что делать с закомментированным кодом, который «может пригодиться»?

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

Как помечать временные решения и недоделанные места?

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

Нужны ли комментарии, если код проходит проверку стандартами?

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