7 ms·
This totally misses the point of the article :( JSON is a fine format for storing configuration data, and any reasonably structured data. So is XML, protocol b
by nine_k 8y ago
This totally misses the point of the article :(
JSON is a fine format for storing configuration data, and any reasonably structured data. So is XML, protocol buffets, what have you.
JSON is a poor format for humans. For a configuration file that an actual human would edit by hand, and read and try to understand later, JSON is a pain.
Comments are mostly useless in a machine-generated and machine-consumed file. They are indispensable for humans, because they are a link to what machines are not doing.
Nice formatting is useless for a machine-consumed file, because they process a stream of bytes. They are indispensable for humans who recognize text very differently.
This boils down to one thing: config files are source code, and need all the amenities that make source code comfortable for humans.
- encoderer 8y agoBeing able to statically analyze and transform configuration is a benefit for humans.
- pier25 8y ago> JSON is a poor format for humans Depends on which kind of humans. For the regular non tech types I agree JSON is poor. A couple of years ago I created a mini spec for a config file so that very low tech paper designers could configure an interactive book. For programmers, JSON works fine in my experience.
- tonyarkles 8y ago> For programmers, JSON works fine in my experience. The author mentions this, and I very strongly agree. What JSON significantly misses is the ability to have comments in your configuration files. I'm not going to hold up the Apache config files as an example of amazing config formats, but... here's an example: https://svn.apache.org/repos/infra/websites/cms/webgui/conf/httpd.conf https://svn.apache.org/repos/infra/websites/cms/webgui/conf/... That's awesome. It describes options that are available and not enabled, and what they do. Right. In. The. File. Comparing that to, say, webpack config... there's a pile of research needed to figure out what options are even available, let alone what they do.
- jlarocco 8y agoYeah, that's the #1 problem with JSON as a config file format, IMO, and the Apache logs, among others, are a perfect example of why. All the other arguments for or against it boil down to personal preference, but not having comments is a real miss.
- datavirtue 8y agoHow does json prevent you from using comments? It does what you tell it to do. It is an object representation. So make your objects have comments...magic.
- andybak 8y ago> For programmers, JSON works fine in my experience. Programmers will maybe cope better but just being a programmer doesn't make you magically immune to poor readability and lack of comments. Most of the points in that article apply to programmers as much as non-programmers. (I agree there is a reasonable debate to be had about programmability - I'm on the fence about this one)
- goostavos 8y agoScale is the important thing here. Even if you're a magical superior human programmer variant, json sucks once you cross over 50 lines. Cloud Formation is a great example of the failures of JSON. Specifying just a single dynamo table with indexes and scaling roles in JSON is a hard to read cluster of a mess. Even with a good idea and json collapse / expand help, large json files are just insufferable to deal with as a human
- Bahamut 8y agoI'd say if you're crossing over 50 lines, it's going to suck no matter what format you're in. Other solutions are not really going to fare any better than JSON at that level.
- int_19h 8y agoXML + XInclude would allow you to break it all into multiple files, for example.
- datavirtue 8y agoCreate objects in code and serialize. Boy that was hard. I feel like everyone on this thread is going mental.
- joezydeco 8y agoJSON is a poor format for humans But do you know what sucks even harder? XML. If I can replace an XML configuration file with JSON then screw it.
- Filligree 8y agoWhy would you limit yourself to those two options? Use TOML or something.
- amelius 8y agoTOML kinda breaks down when you have nested data: https://stackoverflow.com/questions/48998034/does-toml-support-nested-arrays-of-objects-tables https://stackoverflow.com/questions/48998034/does-toml-suppo...
- ChrisSD 8y agoYour link shows nested data structures working? But regardless TOML is a configuration file format (like INI), not a general purpose data structure format (like JSON is).
- TheDong 8y ago> general purpose data structure format General purpose until you need to store dates/times, self-referential structures, enums, etc. json and toml are both serializations of data. I don't think the line you're trying to draw between "configuration file format" and "data structure format" is a well-defined line.
- ChrisSD 8y agoSure it's a blurry line but some formats are better than others for some specific tasks. JSON isn't the right tool for every job but it's a good enough lowest common denominator for data sharing. I wouldn't want to use if for config files or passing complex data but then it's not designed for that.
- juststeve 8y agoIt would be interesting to try Markdown files for configuration data. Documentation and settings in the one file: structured data like arrays can be stored in md tables.
- enturn 8y agoInteresting idea. I did a quick search and found literate-json on github.
- juststeve 8y agoI think it's possible to skip the .md to JSON step? Example is below where an application could either extract values at startup, or is extracted when code is built and deployed? # My App ## Intro about My App Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. ## Prod Server Settings | Host | Port |Operating System| Type | | -------------------------|:-------------:|:--------------:|--------| | webserver1@myapp.com | 80 | Debian |Web | | webserver2@myapp.com | 80 | Debian |Web | | db@cloud.com | 1433 | aws |Database| | webservice.com/api | 80 | aws |Database| --------------------------------------------------------------------- ## Support Information Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. ## Application Roles |Name | Active Directory Group |Description | |-----------------------|------------------------|-----------------------------------------| |System Administrator | MyApp.SysAdmins | Details who should be assigned the role.| |Finance Administrator | MyApp.FinAdmin | " " | |Finance Delegate | MyApp.FinDelegate | " " | |Finance Analyst | MyApp.FinAnalyst | " " | -------------------------------------------------------------------------------------------|
- Twirrim 8y agoWe've been using HOCON for some configuration files. JSON but with comments and a few other more human friendly bits. I don't hate it, but I really dislike it. It's definitely better than JSON for this purpose, but it's still quirky and a bit of a pain.
- base698 8y agoEver edit a 200 line yaml file? There are worse options than JSON.
- raphinou 8y agoI never did, what problems did you encounter?
- mmastrac 8y agoNot the parent commenter, but it really gets tough to figure out _where_ you are in a bunch of nested lists, objects, etc deep down in the yml file. When the schema gets complicated enough you start having to refer back to the documentation to understand what syntax a particular item needs (I'm looking at you, docker compose!) One example from a larger file: networks: macvlan51: driver: macvlan driver_opts: parent: eth0.51 ipam: config: - gateway: 192.168.51.1 subnet: 192.168.51.0/24 Maybe I'm just getting older and dumber, but that hyphen under config seems completely arbitrary to me (and the necessity of it is poorly documented in the manual). This gets magnified to the extreme as your config file grows. Maybe this is a list of objects under a key? Who knows. Edit: OK, it looks like hyphens indicate arrays in the schema but for me it feels like a guess as to which one of these to use for each particular case.
- breck 8y agoWithout the hyphen configs value would be an associative array. With it it’s a list. I’ve been editing long sublime-syntax files recently and I do not like it much. But I’m also not sure if JSON would be better for such a thing.
- jayd16 8y agoWhats the point of a list of tuples? Order? Json seems more immediately obvious and consistent in this case ie [{a:b},...]
- breck 8y ago> Comments are mostly useless in a machine-generated and machine-consumed file. They are indispensable for humans, because they are a link to what machines are not doing. But comments are often code smell—a crutch for poor identifier naming and design. If your names and design are well thought out you rarely need comments and the consumer of your code should be able to understand it using the statically checked source alone—-versus manually having to parse your unchecked human language documentation.
- j88439h84 8y ago> If your names and design are well thought out Sure, but how often does that happen?
- breck 8y agoIt usually happens in good code if the language supports it. But I agree, not enough and comments are great as a stopgap until the thing you need to explain can be explained in the programming language. But sometimes that can’t be and so you do need to resort to comments. It’s like types in doc comments being used as a stopgap until a language added types. I hypothesize (I plan at some point to crunch some data here) the more comments the worse the language, and so you’d see a pattern like Python 3 code having fewer comments on average than Python 2 code.
- breck 8y agoEdit: adding a link to the Clean Code bit about comments, which I think is great advice : https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29#comments-rules https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988c...
- TeMPOraL 8y agoFrom the link, about comments: Use as explanation of intent. Use as clarification of code. Use as warning of consequences. Here's a link to a well-known recent book, half of which is pretty much about why those points are a real and frequent thing, and why code should be much more thoroughly commented than it's recommended by the usual philosophies. https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout/dp/1732102201 https://www.amazon.com/Philosophy-Software-Design-John-Ouste...
- 11235813213455 8y agoI don't feel pain with vscode's settings.json, or .eslintrc for example, because they are autocompletable, allow comments (json5), allow trailing commas (json5), ...
- int_19h 8y agoUnfortunately, it's not actually JSON5, it just supports a few features from the spec. But yes, if every implementation of JSON moved on to JSON5, I don't think we'd be having this discussion.
- hombre_fatal 8y ago> This totally misses the point of the article :( I didn't. There wasn't much to the blog post. In fact, the blog musings are the same criticism we've heard a thousand times. But please don't suggest that I missed some deep point in a trivial blog post when you really just mean "I disagree". I even pointed out a real-world concrete example where JSON config is made pleasant to edit by hand for humans: an IDE like VS Code that pulls in JSON schema. Though since you only doubled down on the blog post's opinion instead of responding to a single point I made, can I say that you missed the points of my comment? You didn't even address my criticism by pitching an alternative. How are we supposed to have a conversation?
- choward 8y ago> I even pointed out a real-world concrete example where JSON config is made pleasant to edit by hand for humans: an IDE like VS Code that pulls in JSON schema. I think the debate here is what "editable by humans" means. If you're using a tool for editing JSON like VS Code, I don't believe you're really editing it by hand. You're using a program that has specific things for JSON that give you to have a pleasant experience editing. I believe editing by hand means using a standard plain text editor and it's a lot worse. Formats that use braces are relatively easy to parse by machines but can be harder to read by humans. Utilizing white space makes things easier for humans to read. A JSON file could have everything on one line. But something like YAML it forces you to use white space and new lines which helps humans to read it.
- int_19h 8y agoMost programming languages don't have significant whitespace, but it doesn't prevent people from writing readable code in them. And I haven't ever seen anybody write a long JSON config any differently - it's indented etc, for the same reason why C code is indented. Still, editing JSON directly by an IDE that still exposes its syntax is "editing by hand", just as editing C in Vim with ctags is still editing by hand. I do have to note though that VSCode uses JSON with extensions. Most obviously, it allows comments. But there are other minor things that make it easier to write (and parse) - e.g. it allows trailing commas in literals.
- zumu 8y ago> JSON is a poor format for humans I have never understood this argument. I'm not saying it's the best, but I find it much much more readable than yml or xml.
- viklove 8y agoI don't understand why people think JSON is a bad format for humans. The ability to write invalid JSON is very hard, and doing so will result in JSON parse errors. Take YAML on the other hand -- simply omitting a dash can result in unintended consequences that will parse just fine: some_collection: - first_entry vs some_collection: first_entry When you're staring at a non-trivial YAML file, it's very hard to spot these errors, and you'll potentially get some very weird behavior in whatever is depending on the config.
- bradleyjg 8y agoNot as bad as YAML isn’t much of an endorsement.
- viklove 8y agoUsually when people complain about JSON they offer YAML as a better option. This article complains about JSON and offers no alternative at all -- what would you suggest?
- bradleyjg 8y agoI think for most cases, old school Unix style is perfectly adequate. Where it isn’t xml is the least bad alternative (and yaml is probably the worst).
- vedantroy 8y agoI feel like JSON is a decent format for storing human-readable configuration data. The use of brackets means if something is broken, you'll know explicitly because your IDE will throw a fit. Formats that are white-space dependent can have subtle errors that aren't easily recognizable on first glance. The 2 problems with JSON are multiline string support and comment support, but JSON5 solves both of those problems. Sure JSON5 isn't JSON, but YAML isn't JSON either. No matter what you're going to need a library to parse a config file, so why not stick to something based on a widely used data-storage format?
- raxxorrax 8y agoI have seen people using additional attributes for comments. That does influence the runtime, which comments should never do, but I thought it as a practical solution. Not optimal of course.
- Corrado 8y agoThough not all JSON parsers accept random attributes. The AWS CloudFormation one, for example, is extreme in its refusal to accept "malformed" JSON. It really frustrates me sometimes.
- caseymarquis 8y agoWhile there are no explicit comments in JSON, you can just add a superfluous string: { useFluxCapacitorComment: "Enables time travel. true or false", useFluxCapacitor: true } I don't mind the formatting, but I'm a professional developer, so my tolerance for complex UIs is abnormal. Written on mobile, so that JSON may look like garbage.
- eitland 8y agoOften not an option: E.g: npm/yarn will complain loudly if you add unexpected lines in package.json IIRC.