Как комментировать файлы 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, у вас есть варианты. Хотя эти решения и не идеальны, но по крайней мере дают возможность включить необходимую документацию, когда она вам нужна.
Перевод статьи Amy Haddad: “JSON Comment Example — How to Comment in JSON Files”
Комментарии