В YAML ровно один символ комментария: знак решётки. Все остальные вопросы о комментариях YAML — как охватить несколько строк, где решётка запрещена, почему ваш встроенный комментарий обрезал значение, сохраняют ли парсеры комментарии — сводятся к пониманию этого единственного правила и его границ. Это руководство охватывает всё: от базового синтаксиса до продакшен-процессов удаления и валидации закомментированных YAML-файлов.
Основы синтаксиса комментариев YAML
В YAML комментарий начинается с символа `#` и продолжается до конца строки. Всё от `#` и далее — только на этой строке — игнорируется парсером. Нет закрывающих разделителей, нет синтаксиса блочных комментариев, нет способа встроить комментарий в середину значения. Один символ, одно правило, без исключений.
Символ комментария и обязательный пробел
В спецификации YAML есть один важный нюанс, который сбивает с толку многих разработчиков: перед встроенным комментарием должен стоять как минимум один пробельный символ. Решётка `#`, приклеенная непосредственно к непробельному символу, комментарием не считается — она разбирается как часть окружающего скалярного значения. Это важнее всего при добавлении комментариев после значений в той же строке.
- Корректный встроенный комментарий: `timeout: 30 # seconds` - пробел перед `#` есть
- Некорректный встроенный комментарий: `timeout: 30# seconds` - без пробела `#` становится частью значения
- Отдельная строка-комментарий: `# This whole line is a comment` - перед ней нет значения
- С комментарным отступом: ` # Indented comment inside a block` - отступ допустим
Warning
Синтаксис комментариев вкратце
Вот три корректных паттерна размещения комментариев в YAML. Любая другая вариация либо идентична одной из них, либо недопустима:
- Комментарий в начале строки: `# comment text` - в колонке 0 или после ведущих пробелов
- Встроенный комментарий после скаляра: `key: value # comment` - один или несколько пробелов перед `#`
- Встроенный комментарий после элемента списка: `- item # comment` - то же правило пробела
Где комментарии разрешены
Комментарии допустимы в подавляющем большинстве мест YAML-документа. Понимание короткого списка мест, где они недопустимы, помогает избежать запутанных ошибок парсинга, которые вовсе не упоминают комментарии.
Разрешённые позиции
- Перед любой парой ключ-значение: размещайте документирующие комментарии над ключом на отдельной строке
- После любого скалярного значения в той же строке: `retries: 3 # max attempts`
- После элемента списка: `- production # primary environment`
- После ключа маппинга (значения ещё нет): `database: # configured below`
- На пустых строках между блоками: свободно используйте строки-комментарии как визуальные разделители
- В начале файла: документирующие комментарии уровня файла обычны для конфигов Kubernetes и CI/CD
Маркеры начала и конца документа
Комментарии также допустимы до и после маркеров YAML-документа `---` (начало документа) и `...` (конец документа). Это позволяет добавлять комментарии с метаданными уровня файла перед телом документа в многодокументных YAML-потоках.
| Расположение | Пример | Комментарий разрешён? |
|---|---|---|
| Отдельная строка | # Full-line comment | ✓ Да |
| После скалярного значения | key: value # note | ✓ Да (нужен пробел) |
| После элемента списка | - item # note | ✓ Да (нужен пробел) |
| Перед началом документа | # Header\n--- | ✓ Да |
| Внутри строки в кавычках | "Say # hello" | ✗ Нет - # литеральный |
| Внутри блочного скаляра | |\n line # note | ✗ Нет - # литеральный |
| Внутри flow-последовательности | [a, b # note, c] | ✗ Нет - синтаксическая ошибка |
| Внутри flow-маппинга | {a: 1 # note, b: 2} | ✗ Ненадёжно |
Note
Многострочные и блочные комментарии
В YAML нет синтаксиса блочных комментариев. Нет эквивалента `/* ... */`, нет heredoc `#!`, нет способа открыть комментарий на одной строке и закрыть на другой. Чтобы закомментировать несколько подряд идущих строк, нужноprefix-овать каждую строку отдельно символом `#`.
Комментарий — это символ решётки, за которым следуют символы, не включающие разрывы строк, и простирающийся до - но не включая - следующего разрыва строки. Комментарий трактуется как пробельный символ.
Традиционный паттерн блочного комментария
Подряд идущие строки с `#` визуально воспринимаются как блочный комментарий, хотя каждая строка технически является независимым однострочным комментарием. Это универсальная конвенция YAML-файлов во всех экосистемах — Kubernetes, GitHub Actions, Docker Compose, Helm-чарты и CI/CD-пайплайны используют этот паттерн:
- `# -----------------------------------------`
- `# Database configuration`
- `# Update connection strings before deploying`
- `# -----------------------------------------`
Горячие клавиши редакторов для многострочных комментариев
Каждый крупный редактор кода поддерживает переключение комментариев на нескольких выбранных строках в YAML-файлах. Выделите строки, которые хотите закомментировать, и используйте горячую клавишу переключения — редактор одновременно добавит или уберёт `#` в начале каждой выбранной строки. Многострочное комментирование в YAML так же быстро, как и в любом другом языке.
- VS Code: Ctrl+/ (Windows/Linux) или Cmd+/ (macOS) - переключает # на выделенных строках
- IDE JetBrains (IntelliJ, PyCharm, GoLand): Ctrl+/ или Cmd+/ - то же поведение
- Vim/Neovim: режим визуального блока (Ctrl+V), выделить строки, I, набрать #, Esc
- Emacs: M-; или comment-region с установленным YAML-режимом
- Sublime Text / TextMate: Ctrl+/ или Cmd+/ - переключает # на всех выделенных строках
Tip
Где комментарии ломают всё
Комментарии безопасны в большинстве контекстов YAML, но есть четыре конкретные ситуации, когда неправильно поставленная `#` приведёт либо к тихой ошибке данных, либо к жёсткому сбою парсинга. Знание их заранее избавляет от часов путаной отладки.
Внутри строк в кавычках
Решётка `#` внутри строки в одинарных или двойных кавычках — всегда литеральный символ, а не комментарий. `message: "Hello # world"` сохраняет строку `Hello # world`. Это корректно и намеренно. Проблема возникает со строками без кавычек: `message: Hello # world` сохраняет `Hello` и трактует `# world` как комментарий — тихо обрезая значение. Заключайте в кавычки любое незакавыченное строковое значение, которое легитимно содержит `#`.
Внутри блочных скаляров (литеральный | и свёрнутый >)
Внутри содержимого блочного скаляра — строк с отступом, следующих за индикатором `|` или `>` — символ `#` не имеет особого значения. Он считается литеральным символом и включается в строку. Закомментировать строки внутри блочного скаляра нельзя. Если нужно исключить содержимое, придётся удалить его полностью, а не комментировать.
Внутри flow-коллекций ([ ] и { })
Flow-последовательности и flow-маппинги записываются в одну строку. Решётка внутри flow-коллекции — это либо синтаксическая ошибка, либо неожиданный результат разбора в зависимости от парсера. Если нужно аннотировать отдельные элементы flow-коллекции, преобразуйте её в блочный стиль (один элемент на строку), где встроенные комментарии работают корректно.
Голая решётка без предшествующего пробела
Как описано в разделе основ, решётка `#`, перед которой нет пробельного символа, не распознаётся как комментарий парсерами, соответствующими спецификации. Значение `port: 8080#dev` разбирается как строка `8080#dev`, а не целое число `8080` с комментарием. Всегда пишите `port: 8080 # dev` с пробелом.
Warning
Удаление комментариев для продакшена
YAML-файлы, ориентированные на разработчиков, часто обильно комментируются в документационных целях. Те же файлы могут потребоваться передать API, инструментам деплоя или системам управления конфигурацией, которые либо отвергают комментарии, либо добавляют лишние накладные расходы на разбор. Удаление комментариев перед передачей — чистое решение.
Когда нужно удалять комментарии
- Эндпоинты API, отвергающие закомментированный YAML - некоторые REST API разбирают тела запросов YAML и падают на комментариях
- Циклы сериализации конфигов - загрузка и повторная запись YAML стандартными парсерами тихо удаляет комментарии
- Снижение шума в diff - при ревью изменений конфигов diff-ы YAML без комментариев фокусируются на реальных изменениях значений
- Оптимизация размера файла - обильно закомментированные манифесты Kubernetes могут заметно уменьшиться без комментариев
- Автоматизированные пайплайны обработки - скриптам, преобразующим YAML, часто нужен чистый вход без логики обработки комментариев
Удалитель комментариев YAML
Вставьте любой YAML-документ и мгновенно удалите все комментарии - чистый результат, готовый к копированию, скачиванию или передаче в API. Полностью работает в вашем браузере без загрузок.
Что удаление комментариев меняет, а что нет
Корректный инструмент удаления комментариев убирает только текст комментария — решётку и всё после неё на этой строке — не изменяя значения, ключи, отступы или структуру. Отдельные строки-комментарии заменяются пустыми строками или удаляются полностью. Полученный YAML разбирается идентично оригиналу для всех значений данных.
Note
Удаление кодом (Python и Node.js)
Если нужно удалять комментарии программно как часть пайплайна, простейший подход в любой стандартной YAML-библиотеке — цикл «загрузить, затем выгрузить»: разберите YAML в структуру данных и немедленно сериализуйте обратно. Комментарии отбрасываются при загрузке и никогда не записываются при выгрузке. Выход — валидный YAML с идентичными данными, но без комментариев. В Python это делает `PyYAML` двумя строками. В Node.js то же самое делает `js-yaml`.
Паттерны комментариев YAML на практике
Хорошо закомментированные YAML-файлы следуют согласованным паттернам, упрощающим их поддержку, ревью и передачу другим участникам команды. Эти паттерны встречаются в манифестах Kubernetes, workflow-файлах GitHub Actions, файлах Docker Compose и values-файлах Helm-чартов.
Комментарии в заголовке файла
Поместите блок комментариев в самое начало файла, чтобы задокументировать его назначение, ответственного и любой критический контекст, неочевидный из самого содержимого. Это стандартная практика в манифестах Kubernetes и плейбуках Ansible. Блок комментариев обычно включает назначение файла, дату последнего изменения и ссылку на связанную документацию или тикеты.
Комментарии-разделители секций
Длинные YAML-файлы — в частности `docker-compose.yml` и `values.yaml` Helm с десятками ключей верхнего уровня — выигрывают от визуальных разделителей секций, помогающих читателям ориентироваться. Строка вида `# -----------------------------------------------` или `# === DATABASE CONFIG ===` перед логической группой ключей — широко принятая конвенция. Используйте валидатор якорей и алиасов YAML, чтобы проверить корректность якорей и алиасов при реструктуризации сильно закомментированных файлов.
Встроенная документация для неочевидных значений
Встроенные комментарии наиболее ценны для значений, которые не объясняют сами себя — магические числа, переопределения для конкретных окружений, значения в неочевидных единицах или поля со взаимозависимостями. Комментарий вроде `timeout: 300 # seconds; must match nginx keepalive_timeout` куда полезнее, чем одно лишь значение. При работе с подстановкой переменных окружения в YAML-конфигах инструмент предпросмотра подстановки env в YAML поможет проверить, как закомментированные дефолты взаимодействуют с рантайм-переопределениями.
- Документируйте единицы: `memory: 512 # MB - increase to 1024 for production`
- Помечайте взаимозависимости: `enabled: false # also disable in config/prod.yaml`
- Объясняйте дефолты: `workers: 4 # matches CPU core count on t3.medium`
- Предупреждайте о необходимых изменениях: `host: localhost # CHANGE before deploying`
- Ссылайтесь на внешние документы: `algorithm: RS256 # see RFC 7518, section 3.3`
Tip
Валидация закомментированного YAML
Добавление комментариев в YAML-файл создаёт новые возможности для синтаксических ошибок, которые не сразу очевидны — решётка внутри строки без кавычек, пропущенный пробел перед встроенным комментарием или случайный комментарий внутри блочного скаляра. Запуск валидатора после правки закомментированного YAML-файла — быстрая страховка от этих проблем.
Что находит валидатор YAML
Валидатор YAML разбирает ваш документ согласно спецификации YAML 1.2 и сообщает о любых синтаксических ошибках с номерами строк и колонок. Он находит неправильно размещённые комментарии, ошибки отступов, появившиеся при добавлении строк-комментариев, дублирующиеся ключи и некорректные скалярные форматы. Вставьте YAML напрямую — без загрузки файлов, без регистрации, и ничего не покидает ваш браузер.
Валидатор YAML
Проверяйте любой YAML-документ по спецификации YAML 1.2 - находит синтаксические ошибки, связанные с комментариями, проблемы отступов и дублирующиеся ключи с точными номерами строк.
Обнаружение дублирующихся ключей в аннотированных файлах
Когда разработчики комментируют пару ключ-значение, а ниже добавляют замену, дублирующиеся ключи — частый результат. Например: закомментированный `timeout: 30` и добавленный под ним `timeout: 60` оставляют закомментированную версию неактивной — но если комментарий случайно удалить или файл обработает инструмент, удаляющий комментарии, дубль станет активным, и меньшее значение тихо победит (или выдаст ошибку, в зависимости от парсера). Детектор дублирующихся ключей YAML находит их до того, как они вызовут проблемы.
Конвертация между форматами с сохранением комментариев
Если вы конвертируете JSON в YAML с помощью конвертера JSON в YAML, учтите, что в выходных данных не будет комментариев — у JSON нет синтаксиса комментариев, так что переносить нечего. Любые документирующие комментарии, которые вы хотите видеть в YAML-выводе, придётся добавить вручную после конвертации. Аналогично инструмент слияния YAML может повлиять на размещение комментариев в объединённых файлах в зависимости от способа слияния.
Сравнение YAML-конфигов до и после правок
При ревью изменений закомментированных YAML-конфигураций — особенно в pull request — подсветчик diff для JSON/YAML-конфигов выносит значимые изменения значений отдельно от правок, состоящих только из комментариев. Это ускоряет ревью кода и снижает риск одобрить случайное изменение значения, спрятанное в diff, забитом обновлениями комментариев.
Key takeaways
- YAML использует единственный символ комментария: `#`. Всё от `#` до конца строки — комментарий.
- Встроенным комментариям нужен пробел перед `#` - написание `value# comment` без пробела — это синтаксическая ошибка или неожиданное значение.
- В YAML нет синтаксиса блочных комментариев - комментируйте несколько строк, prefix-уя каждую по отдельности символом `#`.
- Решётка `#` внутри строк в кавычках и блочных скаляров — всегда литеральный символ, а не комментарий.
- Комментарии невидимы для парсеров - они отбрасываются при загрузке и не могут быть прочитаны обратно PyYAML, js-yaml или любой стандартной библиотекой.
- Используйте удалитель комментариев YAML, чтобы убрать комментарии перед передачей YAML в API или инструменты деплоя.
- Всегда проверяйте валидатором YAML после добавления встроенных комментариев, чтобы ловить тихие баги усечения значений.