JSON treats every character as data
JSON is designed to represent structured data in a form that software can read consistently. Its grammar allows objects, arrays, strings, numbers, booleans, and `null`—but no comment markers. In formats such as JavaScript, `//` or `/ ... /` can mark text for people that the program should skip. JSON has no corresponding rule, so those characters are not harmless annotations: they make the document invalid wherever the parser does not expect them.
That strictness matters because JSON is exchanged among many languages and tools. A parser can reject unexpected syntax instead of guessing whether a line is a note, part of a value, or a mistake. The same rule keeps the format predictable across systems.
Why notes can break a working file
Suppose a configuration file contains a setting followed by `// used for testing`. A person may understand the note, but a standard JSON parser encounters the slash where the grammar permits no comment and stops with a syntax error. The application may then fail to load the entire file, not just ignore the note.
There are practical workarounds. Put explanatory text in an ordinary string field—such as a `description` property—if the software that reads the file is built to accept it. Or keep notes in a separate document. Some tools also accept JSON-like formats that add comments, but those are extensions, not standard JSON; a strict parser may reject their files.
The tradeoff behind the rule
Leaving comments out makes JSON less convenient for annotated configuration, but avoids giving every parser extra syntax to interpret. A file that looks almost like JSON is not necessarily valid JSON: whether comments work depends on the specific format and the software reading it.
