Original article: https://www.freecodecamp.org/news/json-comment-example-how-to-comment-in-json-files/

Si has estado teniendo problemas para agregar comentarios a un archivo JSON, hay una buena razón: JSON no cuenta con soporte para comentarios.

"Elimine los comentarios de JSON porque vi gente que los estaba usando para mantener directivas de parsing, una práctica que podría haber destruido la interoperabilidad", escribe Douglas Crockford, quien popularizo el formato de información basado en texto.

Sin embargo, existe una solución alternativa y de eso trata este artículo: como agregar comentarios a un archivo JSON.

Agregar información como comentarios

Una manera de eludir el problema de los comentarios es agregar información que funcione como comentarios a tu archivo JSON.

Ahora veamos un ejemplo, iniciando con la siguiente información en nuestro archivo JSON:

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

Ahora agreguemos otro par clave-valor (key-value) que servirá como nuestro comentario, lo podemos ver en la primera línea de código del siguiente ejemplo:

{
   "_comentario1": "esto es un comentario",
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

A continuación, otro ejemplo. Esta vez, usaremos dos guiones bajos al inicio y al final de la clave (key).

 "__comentario2__": "esto es otro comentario",

Los guiones bajos ayudan a diferenciar el comentario del resto de nuestra información en el archivo JSON.

Solo una pequeña advertencia

Solo hay un detalle importante a tener en cuenta.

Los comentarios que agregamos a nuestro archivo JSON están incluidos en el objeto JSON. En otras palabras, los comentarios son tratados como información.

Esto es a lo que nos referimos:

Este es el código en nuestro archivo, data.json:

{
   "_comentario1": "este es mi comentario",
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

Ahora vamos a leer la información del archivo, read_comments.py:

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

El resultado incluye nuestro comentario:

{'_comentario1': 'este es mi comentario', 'sport': 'basketball', 'coach': 'Joe Smith', 'wins': 15, 'losses': 5}

Incluso podemos extraer el valor del comentario del objeto JSON: este es mi comentario:

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

Ten en cuenta que el comentario solo es un comentario para el desarrollador—no para la computadora.

Un tipo diferente de comentario

Esta práctica de agregar comentarios en archivos JSON es diferente a los comentarios en los lenguajes clásicos de programación, tal es el caso de Python, donde es normal que los comentarios sean ignorados cuando se ejecute el programa.

# Este es mi comentario
word = "house"
for letter in word:
   print(letter)

Cuando ejecutamos el programa Python anterior, obtenemos las letras de la palabra, "house". Pero aquí no vemos el comentario, ya que es ignorado.

Otras opciones para comentar

JSMin es otra opción para considerar.

JSMin es una herramienta que elimina los espacios en blanco y los comentarios adicionales de archivos JavaScript. Pero esta también funciona en archivos JSON. JSMin elimina comentarios de archivos JSON antes de que sean analizados (parsed).

Así que, como ya vimos, existen algunas opciones cuando se trata de agregar comentarios en archivos JSON. A pesar de que no sean las mejores soluciones, al menos existe la forma de incluir documentación para cuando sea necesario.

Escribo sobre como aprender a programar y las mejores formas de hacerlo (amymhaddad.com).