Don’t use JSON for your config files.

Everyone loves JSON. I love JSON. JSON is great at storing complex data structures to be written and read by programs. It can even be written such that it’s fairly easily human readable. Yet, the JSON format is missing comments. Those things we mostly agree we need for anything non-trivial. This is completely fine for anything written by and for programs –I might have named this article, “Don’t use JSON for your config files which humans might have to edit,” but I opted for brevity –but not so great when our meat computers are involved.

Some context is in order. Lately, I have been working on some CloudFormation templates. CloudFormation is a way to textually describe to AWS what you want to build. These files might contains things like a VPC object, and a couple subnet objects, and a couple objects bringing the VPC and subnets together, and then you fill that full of security groups, and autoscaling groups or EC2 instances, and you end up with a very long file. These files can easily become hundreds of lines long. I would really love to leave some comments for 3-months-from-now me, but I can’t, because it’s JSON.

I was going to spend a few paragraphs discussing the history of comments in an effort to explain why they are important, but there really isn’t much to discuss. If you look at the popular, early  programming languages, COBOL, LISP, FORTRAN, they have comments. Assembly has comments. If you examine Ada Lovelace’s notes on Babbage’s Analytical Engine, you find that she describes note G (regarded as the first program). I will take this evidence as indicating the self evidence of comments.

The question then, is if comments are so prevalent, why doesn’t JSON have them? The answer is because JSON is a data encoding format meant to encode complex data structures for storage or transfer between programs (javascript <-> web server). It wasn’t designed for scripting. So lets please stop using a screw driver to hammer in a nail. Our future selves will appreciate it.

Might I suggest YAML instead?


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: