Как комментировать файлы JSON

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

“Я убрал комментарии из JSON, потому что увидел, что люди используют их для парсинга директив — практика, которая разрушила бы совместимость”, — пишет Дуглас Крокфорд, популяризировавший текстовый формат данных.

Однако есть и обходной путь. И эта статья посвящена именно ему.

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

Чтобы обойти проблему комментариев, добавьте в свой файл JSON данные, которые функционируют как комментарии.

Давайте рассмотрим это на примере. Начнем с файла JSON, в котором содержится следующая информация:

{
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

Теперь давайте добавим еще одну пару ключ-значение, чтобы она служила для нас комментарием —  как вы можете видеть в первой строке кода ниже:

{
   "_comment1": "здесь мой комментарий",
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

Вот еще один пример. На этот раз мы используем два подчеркивания — в начале и в конце ключа:

"comment2": "здесь другой комментарий",

Подчеркивание помогает отличить комментарий от остальных данных в файле.

Небольшое предостережение

Есть одна важная деталь, которую нужно иметь в виду.

Комментарии, которые мы добавили в файл JSON, включены в объект JSON. Другими словами, комментарии рассматриваются как данные.

Вот что имеется в виду.

{
   "_comment1": "здесь мой комментарий",
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

Теперь мы собираемся прочитать эти данные из файла read_comments.py:

import json
with open("data.json", mode="r") as j_object:
   data = json.load(j_object)
print(data)

Результат включает в себя наш комментарий:

{'_comment1': 'здесь мой комментарий', 'sport': 'basketball',
'coach': 'Joe Smith', 'wins': 15, 'losses': 5}

Мы даже можем извлечь значение комментария из объекта JSON: this is my comment:

import json
 
with open("data.json", mode="r") as j_object:
   data = json.load(j_object)
   print(data["_comment1"])

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

Другой тип комментария

Эта практика комментирования JSON отличается от комментариев в языках программирования, таких как Python, которые обычно игнорируются при запуске программы.

# Здесь мой комментарий
word = "house"
for letter in word:
   print(letter)

Когда мы запускаем программу Python, приведенную выше, мы получаем буквы в слове “house”. Но мы не видим комментария. Он был проигнорирован.

Варианты комментирования

JSMin — это еще один вариант, стоящий рассмотрения.

Это инструмент, который удаляет лишние пробелы и комментарии из файлов JavaScript. Но он также работает и с файлами JSON. JSMin удаляет комментарии из файлов JSON до того, как они будут обработаны.

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

Читайте также:

• 3 фундаментальных постулата JS, приближающих вас к Pro-статусу
• Добро пожаловать в ад…зависимостей JavaScript
• Движок JavaScript: что внутри

---

Перевод статьи Amy Haddad: “JSON Comment Example — How to Comment in JSON Files”