Artigo original: JSON Comment Example — How to Comment in JSON Files

Se você estiver tendo problemas em adicionar comentários em seu arquivo JSON, aqui está um bom motivo: o JSON não dá suporte a comentários.

“Removi os comentários do JSON, pois eu vi que pessoas estavam usando os comentários para manter diretivas de parsing, uma prática que destruiria a interoperabilidade,” escreveu Douglas Crockford (texto em inglês), que popularizou o formato de dados baseado em texto.

No entanto, existe uma maneira de contornar isso. É disso que trata este artigo: como adicionar comentários ao seu arquivo JSON.

Adicionar dados como comentários

Uma maneira de contornar a questão dos comentários é adicionar dados ao seu arquivo JSON que funcionem como comentários.

Vamos ver um exemplo, começando com essas informações em nosso arquivo JSON:

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


Agora, vamos adicionar outro par chave-valor que servirá como nosso comentário, o qual você pode ver na primeira linha do código abaixo:

{
   "_comment1": "Esse é o meu comentário",
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

Aqui temos outro exemplo. Dessa vez, usamos duas sublinhas no início e no fim da chave:

 "__comment2__": "Esse é outro comentário",

As sublinhas ajudam a diferenciar o comentário do resto dos dados no seu arquivo.

Um aviso

Há um detalhe importante que deve ser observado.

Os comentários que adicionamos em nosso arquivo JSON são incluídos no objeto JSON. Em outras palavras, os comentários são tratados como dados.

É isso o que queremos dizer.

Esse é o código do nosso arquivo, data.json:

{
   "_comment1": "Esse é o meu comentário",
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

Agora, vamos ler esses dados a partir do arquivo, read_comments.py:

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

O resultado incluirá nosso comentário:

{'_comment1': 'Esse é o meu comentário', 'sport': 'basketball', 'coach': 'Joe Smith', 'wins': 15, 'losses': 5}

Podemos até extrair o valor do comentário do objeto JSON: Esse é o meu comentário:

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

Lembre-se de que o comentário é um comentário apenas aos olhos do desenvolvedor — mas o computador o enxerga como dados.

Um tipo diferente de comentário

Essa prática de comentar em JSON é diferente dos comentários em linguagens de programação, como o Python, que tipicamente os ignoram quando o programa é executado.

# Aqui está o meu comentário
word = "house"
for letter in word:
   print(letter)

Quando executamos o programa em Python acima, obtemos as letras da palavra, “house”, mas não vemos o comentário. Ele é ignorado.

Opções para comentar

O JSMin é outra opção a se considerar.

Ele é uma ferramenta que remove espaços em branco e comentários dos arquivos JavaScript. Mas ele também funciona com arquivos JSON. O JSMin remove comentários dos arquivos JSON antes de eles passarem pelo parsing.

Portanto, existem opções para se comentar em arquivos JSON. Embora não sejam soluções perfeitas, pelo menos, há formas de incluir a documentação de que você precisa quando você precisa dela.

A autora escreve sobre aprender a programar e sobre as melhores maneiras de fazer isso. Visite o site da autora em amymhaddad.com.