Комментарии в JSON: как добавлять и использовать без нарушения стандартов

kirilljsx

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

Знание этих методов поможет писать читаемый код, упростит командную работу и сэкономит время на отладку. Мы пройдёмся по хаккам, расширениям и лучшим практикам, чтобы JSON оставался валидным и удобным.

Почему JSON не поддерживает комментарии

Стандарт JSON определяет только данные: строки, числа, объекты, массивы, true, false и null. Комментарии вроде // или /* */ здесь не предусмотрены, чтобы парсеры во всех языках работали одинаково строго. Это упрощает реализацию, но усложняет жизнь разработчикам. Представь конфиг с сотней параметров — без пояснений новичок запутается.

Например, в объекте с настройками сервера легко забыть, что делает поле “timeout: 30000”. Добавь комментарий // в миллисекундах — и JSON.parse() выдаст ошибку. Из-за этого команды часто ищут обходные пути. Такие хаки популярны в проектах на JavaScript, Python или даже C++, где JSON используется для конфигов.

Вот основные причины отсутствия поддержки:

Универсальность: JSON парсится везде без лишних фич.
Безопасность: Нет риска от случайных комментариев в пользовательских данных.
Компактность: Формат остаётся лёгким для сетевой передачи.

Проблема	Последствие
Нет //	Ошибка парсинга
Сложный конфиг	Трудно понять логику
Командная работа	Больше вопросов коллегам

Хаки для добавления комментариев в чистый JSON

Один из простых способов — использовать специальные ключи вроде “_comment”. Это поле игнорируется приложением, но парсер его пропустит как обычное значение. Подходит для конфигов, где код сам фильтрует такие ключи. Например, в настройках API можно добавить “_comment”: “Значение в миллисекундах”.

Другой подход — ключи с описанием, типа “timeout_desc”: “Задержка в мс”. Но это засоряет структуру, особенно если параметров много. В больших объектах такие “мусорные” ключи накапливаются, усложняя чтение. Ещё вариант — вставлять null в массивы как placeholders для комментариев, но это работает только для списков.

Рассмотрим варианты подробнее:

_comment: Универсальный ключ для текста. Пример: {“_comment”: “Серверные настройки”, “port”: 8080}.
Двойные ключи: “key”: value, “key#”: “пояснение”. Парсер увидит оба.
Null в массивах: [1, null, “коммент”, 2] — преобразуется в коде.

Метод	Плюсы	Минусы
_comment	Простой, валидный	Нужно игнорировать в коде
Двойные ключи	Самодокументируется	Мусорит объектом
Null-маркеры	Для массивов	Не для объектов

JSON-подобные форматы с нативной поддержкой комментариев

Если стандартный JSON не подходит, переходи на расширения вроде JSON5. Этот формат добавляет // для однострочных и /* */ для многострочных комментариев, сохраняя совместимость с JSON. Парсеры для JSON5 есть в Node.js, Python и браузерах. Пример: {“key”: 42 // это число } — после очистки становится чистым JSON.

Ещё вариант — jsonc (JSON с комментариями), популярный в VS Code и TypeScript. Он использует регулярки для удаления // до конца строки. Реализация простая: функция чистит файл перед JSON.parse(). В проектах с конфигами webpack или tsconfig.json это норма. Такие форматы удобны, но требуют доп. инструментов.

Ключевые особенности:

JSON5: Поддержка чисел без кавычек, trailing commas.
jsonc: Только комментарии, минимальные изменения.
Hjson: Читаемый синтаксис с отступами.

Таблица сравнения:

Формат	Комментарии	Совместимость	Пример
JSON5	// и /* */	Высокая	{“a”: 1 // коммент}
jsonc	Только //	Отличная	{“b”: 2 // пояснение}
Hjson	# и многостр.	Средняя	a: 1 # коммент

Парсинг и инструменты для работы с комментариями

Чтобы обрабатывать JSON с комментариями, пиши препроцессор. На JavaScript используй регулярку ///[^\r\n]*/g для удаления //комментариев. После очистки стандартный парсер сработает. В Python библиотека json5lib делает это автоматически. Для TypeScript есть jsonc-parser из VS Code.

Пример кода на JS:

function stripComments(jsonStr) {
  return jsonStr.replace(/\\\/\\\/[^\\r\\n]*/g, '');
}
const data = JSON.parse(stripComments('{"key": 1 // тест}'));

Такой подход работает для большинства случаев. В C++ используй stringstream для фильтрации. Главное — экранировать спецсимволы вроде " в комментах.

Полезные инструменты:

json5lib (Python).
jsonc-parser (TS/JS).
strip-json-comments (npm).

Когда отказаться от комментариев в JSON

Комментарии полезны, но иногда лучше документацию вне файла. Используй JSON Schema для описания структуры — там поля с description. Для API подойдёт OpenAPI со Swagger. Это сохранит JSON чистым, а пояснения — отдельно.

В больших проектах комменты в JSON устаревают при изменениях. Schema живёт дольше и валидирует данные. Подумай о README или отдельном .md с примерами. Так конфиги остаются лёгкими, а знания — актуальными.

Остаётся место для экспериментов: комбинируй хаки с инструментами под задачу.