Better project hand-over take-over documentation

Should you be happening to work with composer, npm, bower or any other dependency or project manager which uses JSON, here's a handy tip for those of you who actually want or need to document things in a bit more inline or literate fashion.

As you may probably know by now, JSON hardly allows for any commenting. It accepts only but a few comments at certain places but overall this is discouraged as this SO topic addresses the question and from what I learned during my own experimentation. The rules are quirky and hardly reliable way of storing inline information.

That is, until CSON came along. Goodbye lame JSON files and brackets, Hello CSON and indents. Admittingly, I shall state that CSON is not completely pristine in this sense either. For one it has all the properties the CoffeeScript syntax has concerning objects. That is:

• significant whitespace
• implicit brackets for objects keys and values are allowed

For any Pythoneers amongst you: the first is a very characteristic of your language and long-time trademark of the language: omission of brackets and nesting blocks per indent instead (it wasn't the first). The second one violates a rule in the Zen of Python: "Explicit is better than implicit" and often I find, in those cases it refers to where things might become ambiguous, these rules extend to CoffeeScript 1:1. One would, as a best practice, do well to inform themselves before becoming adventurous.

Probably your best bet is to just have it boilerplated out first: because we are lazy and because the scripts are more precise than we are + guaranteed same results if nothing out of the ordinary is done in the source files - if unreadable it will fail anyway.

You will need to have Node.js installed. Then do e.g.

npm i -g cson season

json2cson composer.json > composer.cson

Now you have a .cson brand new copy off a clean .json. You can go add multi/single-line comments now which may explain the rationale behind using a certain required dependency or the motivation to leave certain ones behind, or why they should belong in dev. You name it.

After which:

csonc composer.cson

composer validate && composer update

And voila: you have documentation inline of your project source files: now no successor has to guess their way around the reason behind certain things: they can start right with the very foundation of many applications - the libraries/packages it uses.

One big downside is that you would have to conjure a solution if you happen to do a lot of:

npm i something --save

You could then do another round trip, back from .json to .cson but wouldn't have any comments so a merge of diff in those files would be required.

Given all that trouble, one may just as easily revert back to plain ignoring .json rules and type in comments as e.g.

% this is a new comment

And have awk, grep or sed pull those out before you start an automated process. It is just as trivial to have a composer.tpl template file generate a composer.json from just a simple shell script using standard nix tools (no npm needed).