It makes total sense to omit comments, because JSON is optimized for machine-readability and interoperability (simple spec, simple implementation, no extension mechanism, fast to parse). Putting comments in would compromise it for that purpose.

JSON isn't a great config file format, if your config file is meant to be human-edited. But the solution is simple; use a format designed for human editing.

Config files need UI design too.

During Akka and Play 2.0 development, we approached this by starting from the hand-rolled parsers found in Akka 1.2 and Play 1.2 (both had ad-hoc parsers to support a "pretty" config file format). We took the aesthetic preferences of the hand-rolled parsers seriously, and came up with HOCON: https://github.com/typesafehub/config (scroll down to "JSON Superset"), https://github.com/typesafehub/config/blob/master/HOCON.md

The HOCON format is a superset of JSON and also happens to be mostly compatible with the Play and Akka 1.2 ad hoc parsers (which were independently developed, so two data points on what people wanted).

HOCON is roughly similar to YAML in complexity. Like YAML the spec is pretty long ( http://www.yaml.org/spec/1.2/spec.html ). And the Typesafe Config and SnakeYAML jars have pretty comparable amounts of bytecode in them.

HOCON or YAML would be terrible formats for an API or something like that, and they're painful to implement, but I strongly prefer them to JSON for human-maintained configuration.

Anyway, I think the genius of JSON was its focus on machine interoperability rather than trying to do everything, that's why it works so well for machine interoperability. But it doesn't mean you have to use it for everything.