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

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

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

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

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

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

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

Итог = СуммаДокумента - СуммаСкидки; // без учёта бонусных баллов

Комментарий нельзя разорвать переносом строки: если текст длинный, каждую строку начинайте с //. Также нельзя вставить комментарий внутрь выражения посередине строки — всё, что следует после //, перестаёт быть кодом. Например, конструкция А = 5 // комментарий + 3; приведёт к синтаксической ошибке, так как закрывающая часть выражения закомментирована.

Отдельный случай — директивы компиляции и инструкции препроцессору. Они начинаются с символов & и # и комментариями не являются: &НаСервере или #Если Сервер Тогда обрабатываются платформой. Не пытайтесь «закомментировать» их слэшем — это изменит поведение модуля или вызовет ошибку.

Как быстро закомментировать блок кода

Ручная расстановка слэшей в десятках строк отнимает время, поэтому в конфигураторе предусмотрены горячие клавиши. Выделите нужный фрагмент и нажмите Ctrl + Num / (клавиша деления на цифровом блоке клавиатуры) — к каждой строке добавится //. Обратное действие — Ctrl + Shift + Num / снимает комментарий со всех выделенных строк.

Те же команды доступны через меню «Текст» в редакторе модуля: «Блок» → «Добавить комментарий» и «Удалить комментарий». Если цифрового блока на клавиатуре нет (компактные ноутбуки), команды можно переназначить в настройках конфигуратора или использовать пункт меню.

1. 1
   Выделите мышью или клавишами Shift+стрелки нужные строки в модуле
2. 2
   Нажмите Ctrl+Num/ — платформа добавит // в начало каждой строки
3. 3
   Запустите проверку синтаксиса (Ctrl+F7) и убедитесь, что ошибок нет
4. 4
   Чтобы вернуть код, выделите фрагмент и нажмите Ctrl+Shift+Num/

При массовом комментировании следите за вложенными комментариями: если строка уже содержала //, после снятия комментария со всего блока она тоже станет активным кодом. Проверяйте результат синтаксической проверкой модуля (Ctrl+F7) сразу после операции.

Что писать в комментариях, а что — нет

Главный критерий полезного комментария: он содержит информацию, которую нельзя вывести из самого кода. Комментарий // увеличиваем счётчик на 1 над строкой Счетчик = Счетчик + 1; бесполезен и только загромождает модуль. Полезный комментарий объясняет причину, ограничение или неочевидное следствие решения.

Уместные ситуации для комментариев:

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

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

Стандарты оформления в командной разработке

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

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

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

Комментарии при отладке и временном отключении кода

Комментирование — рабочий приём при поиске ошибки: временно отключают подозрительный фрагмент, проверяют поведение, затем возвращают код или сужают область поиска. Здесь важна дисциплина: помечайте временно отключённые блоки понятной пометкой (например, // ОТЛАДКА: отключено до выяснения причины), чтобы случайно не оставить их в рабочей версии.

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

Комментарии в запросах и других местах конфигурации

Язык запросов 1С поддерживает тот же синтаксис // — комментарий действует до конца строки текста запроса. Это удобно для пояснения сложных соединений и виртуальных таблиц. Учтите: комментарий внутри текста запроса виден только в модуле, при трассировке запроса в СУБД его не будет.

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

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

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

Читаемость модуля

Норма

Комментарии объясняют причины решений и ограничения

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

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

Синтаксис после правок

Норма

Проверка модуля (Ctrl+F7) проходит без ошибок

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

Ошибки из-за закомментированной части выражения

Экспортные методы

Норма

У процедур и функций есть структурированный заголовок

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

Назначение методов понятно только из чтения тела

Мёртвый код

Норма

Неиспользуемые фрагменты удалены, история в хранилище

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

Модули содержат большие массивы закомментированного кода

Частые вопросы о комментировании в 1С

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

Нет, специального синтаксиса для многострочных комментариев платформа не предоставляет. Каждую строку нужно начинать с //. Для блока кода используйте выделение и сочетание Ctrl+Num/ — это фактически заменяет многострочный комментарий.

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

Нет. Текст после // отбрасывается на этапе компиляции модуля и в исполняемый код не попадает. Можно писать развёрнутые пояснения, не опасаясь замедления работы программы.

Как закомментировать код, если на клавиатуре нет цифрового блока?

Используйте меню «Текст» → «Блок» → «Добавить комментарий» в редакторе модуля. При необходимости в настройках конфигуратора можно назначить команде другое сочетание клавиш.

Можно ли комментировать текст запроса?

Да, в языке запросов работает тот же синтаксис // до конца строки. Комментарии удобны для пояснения соединений и условий, но помните, что при выполнении запроса они отбрасываются.

Нужно ли удалять комментарии перед сдачей конфигурации заказчику?

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

Как быстро найти все свои временные комментарии в большой конфигурации?

Договоритесь о единой метке (например, ОТЛАДКА или TODO) и используйте глобальный поиск по конфигурации (Ctrl+Shift+F) с поиском по текстам модулей. Единообразная метка позволяет найти все временные места за одну операцию.