К статье
Практический материал

Другое · 7 мин

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

Правила оформления комментариев в 1С:Предприятии: где оставлять заметки, что не стоит комментировать и как проверять код перед обновлением.

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

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

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

Зачем нужны комментарии в конфигурации 1С

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

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

Где комментарии помогают, а где только мешают

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

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

Как оформлять комментарии к процедурам и функциям

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

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

Комментарии внутри алгоритма и бизнес-правил

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

Бизнес-правила меняются чаще, чем программный код, поэтому комментарии к ним требуют регулярной проверки. Если условие скидки изменено в договоре, комментарий в коде должен быть обновлён в той же правке. Иначе через полгода разработчик будет полагаться на устаревшее описание и введёт ошибку в расчёте.

Проверка и поддержка комментариев при обновлении

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

Порядок работы с комментарием
  1. 1
    Определите, не проще ли переименовать переменную или процедуру
  2. 2
    Напишите комментарий только к неочевидной бизнес-логике
  3. 3
    Проверьте синтаксис и сохраните объект
  4. 4
    Сопоставьте комментарий с текущей логикой при следующем изменении

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

Опасные места и ограничения

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

Типичные ошибки
01
Комментирование каждой очевидной строки, что засоряет модуль и быстро устаревает
02
Оставление закомментированного кода в рабочей конфигурации на случай возврата
03
Указание паролей и персональных данных в комментариях
04
Необновление комментария после изменения бизнес-правила

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

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

Как выбрать, что именно комментировать

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

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

Итог

Что важно запомнить

Пишите комментарии там, где код не раскрывает бизнес-смысл, обновляйте их вместе с логикой и не храните в них конфиденциальные данные.

Часто задаваемые вопросы

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

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

Можно ли оставлять закомментированный код «на всякий случай»?

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

Что делать, если комментарий стал неактуальным после изменения?

Обновите комментарий в той же правке, в которой меняется логика. Устаревшее описание может ввести в заблуждение другого разработчика и стать причиной ошибки при поддержке.

Безопасно ли хранить пароли в комментариях кода 1С?

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

Как проверить, что комментарий не сломал код?

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