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

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

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

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

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

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

// Проверяем остаток с учетом резерва, чтобы не допустить отгрузку
// товара, уже обещанного другому покупателю.
ДоступныйОстаток = СвободныйОстаток - Резерв;

Если Количество > ДоступныйОстаток Тогда
Отказ = Истина;
КонецЕсли;

КурсПересчета = 1.2; // поправочный коэффициент по договору с поставщиком

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

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

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

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

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

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

Стандарты разработки 1С требуют снабжать описанием каждую процедуру и функцию программного интерфейса — то есть размещённую в разделе ПрограммныйИнтерфейс общих модулей и модулей менеджеров. Заголовок располагается перед объявлением метода и имеет фиксированную структуру.

Стандартный шаблон включает описание назначения, секцию «Параметры» с перечислением имён, типов и смысла, секцию «Возвращаемое значение» (для функций) и при необходимости пример вызова:

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

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

1. 1
   Напишите одну-две строки: что делает функция и в каком случае её вызывают
2. 2
   Добавьте секцию «Параметры» с именем, типом через дефис и назначением каждого параметра
3. 3
   Добавьте секцию «Возвращаемое значение» с типом и смыслом результата, включая особые случаи (Неопределено, 0, пустая коллекция)
4. 4
   При неочевидном использовании добавьте короткий пример вызова
5. 5
   Проверьте, что описание совпадает с фактическим поведением после всех правок

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

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

// +Доработка Иванов 12.03: по требованию учетной политики
//   скидка не применяется к товарам категории "Акция".
// Типовой код:
//Если СуммаДокумента > 100000 Тогда
Если СуммаДокумента > 100000 И Не ЭтоАкционныйТовар Тогда
// -Конец доработки

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

Области и структурирование модуля

Директивы #Область и #КонецОбласти формально не комментарии, но выполняют схожую роль — они объясняют структуру модуля и позволяют сворачивать фрагменты в редакторе. Стандарт предписывает размещать код общих модулей в областях ПрограммныйИнтерфейс, СлужебныйПрограммныйИнтерфейс и СлужебныеПроцедурыИФункции.

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

Инструменты автоматической проверки комментариев

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

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

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

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

Заголовки экспортных методов

Норма

У каждого метода программного интерфейса есть описание, секции параметров и возвращаемого значения

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

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

Закомментированный код

Норма

В модуле нет блоков отключенного кода, либо каждый снабжён пометкой с причиной и датой

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

Найдены фрагменты кода под // без пояснений

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

Норма

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

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

Изменения не отличаются от типового кода, найти их можно только сравнением

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

Язык запросов 1С имеет собственный синтаксис комментариев — тот же двойной слэш // внутри текста запроса. Комментарии уместны для пояснения виртуальных таблиц с неочевидными параметрами, сложных соединений и причин выбора «ЛЕВОЕ СОЕДИНЕНИЕ» там, где напрашивается внутреннее. Имейте в виду: текст запроса — это строка в коде, поэтому комментарии запроса живут внутри кавычек и не мешают компилятору модуля.

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

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

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

Да. Выделите нужные строки в редакторе модуля и нажмите Ctrl+Num/ (или используйте команду контекстного меню «Закомментировать») — конфигуратор добавит // к каждой строке. Снятие комментария выполняется аналогичной командой. Это удобно при отладке, но перед завершением работы такие блоки нужно либо удалить, либо снабдить пояснением.

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

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

Чем отличается комментарий в коде от комментария в запросе 1С?

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

Обязательно ли писать описание процедуры по стандарту 1С?

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

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

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

Как пометить место, требующее доработки в будущем?

Используйте единообразную метку, например «TODO» или «ДОРАБОТКА», с пояснением, что именно нужно сделать и почему текущее решение временное. Единый формат метки позволяет находить все такие места глобальным поиском по конфигурации перед релизом.