For quite some time, I wondered about this: “why the hell are comments forbidden in json files?”.
The short answer is: Douglas Crockford cared about interoperability (https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaGSr).
The problem is that nowadays, many CLI tools make us of json files to store their configuration. It’s nice because the syntax is pretty lightweight and because it’s really easy to parse, but that’s where it ends because you know what? Comments are pretty darn useful in configuration files..
Unfortunately, as it stands, many of those tools (or at least the parsers they rely upon) choose not to accept comments. As Douglas states, nothing prevents us from sending json files through a minifier to get a comments-free version but… but it’s just a pain to have to do that before passing json files around; worse so when you need to have the file available on disk for some tool and even worse when that file needs to have a certain name (e.g., tsconfig.json).
Some tools do add support for comments, but then you realize that any surrounding tools must also accept that, which is often not the case or takes a while to get there. So that’s that, and IDEs which will complain if you start adding comments to json files (and rightly so..).
All in all, my opinion about this matter now is that json is just not the answer for configuration files. Since json does not support comments, then don’t use json, use something else, don’t try to hack your way around.
What should we use instead? Who cares, as long as it supports comments and doesn’t force you into hacks just to be able to comment things that need be!
If you’re in the JS world then why not simply JS modules? There you get the benefit of directly supporting more advanced use cases (e.g., configuration composition, logic, etc).