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.

▲

iainmerrick 4 hours ago | parent [-]

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.

▲

dgacmu an hour ago | parent | next [-]

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

	▲	iainmerrick 25 minutes ago \| parent [-]
		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.

▲

mikkupikku 3 hours ago | parent | prev [-]

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.