Hacker News Reader

Comment by iainmerrick | Hacker News Reader

Right, and then when you don't work on it for 6 or 12 months, you come back and find that now you don't understand it either.

View on HN

Part of doing it well is adding comments as you add options. When I used vim, every line or block in the config had an accompanying comment explaining what it did, except if the config’s name was so obvious that a comment would just repeat it.

That's a good call. It's a big problem for JSON configs given pure JSON's strict no-comments policy. I like tools that let you use .js or better yet .ts files for config.

A lot of json parsers will permit comments even though it isn't meant to be valid. Worth trying it, see if a comment breaks the config, and if not then use comments and don't worry about it.

For reference, jq and python don't allow comments.

Or consider jsonc - json with comments - or jwcc - which is json with comments and trailing commas to make life a little easier.

https://jsonc.org/

https://nigeltao.github.io/blog/2021/json-with-commas-commen...

There are a lot of implementations of all of these, such as https://github.com/tailscale/hujson

I like this idea a lot, and pushed for json5 at a previous job, but I think there are a few snags:

- it's weird and unfamiliar, most people prefer plain JSON

- there are too many competing standards to choose from

- most existing tools just use plain JSON (sometimes with support for non-standard features, like tsconfig allowing trailing commas, but usually poorly documented and unreliable)

Much easier just to make the leap to .ts files, which are ergonomically better in almost every way anyway.

Reply on news.ycombinator.com