News for hackers. Stuff that matters.
Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Monday April 30, 2012 @09:16PM (#3912494)
This makes sense to me. JSON is designed to simply hold data so there shouldn't need to be any comments.

If it's related to configuration then there should be documentation regarding what is and isn't supported. If it's simply data you're sending across the wire then there should be documentation somewhere; you wouldn't want to waste bandwidth transmitting comments.

Re:Douglas Crockford: Why I removed comments from JSON by njharman on Monday April 30, 2012 @10:20PM (#3912682)
> simply hold data so there shouldn't need to be any comments.

How does that follow? Usually "data", 5.23423, needs commenting more than most. What the hell is that? Why 5 decimal places?

Also comments in config files are for many things; when file was created, change history, by whom, who to contact with problems, warnings not to edit as it's managed via chef/puppet.

Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Monday April 30, 2012 @10:32PM (#3912723)
>How does that follow? Usually "data", 5.23423, needs commenting more than most. What the hell is that? Why 5 decimal places?

You would already know the answer before seeing the JSON file so I'm not sure why you care.

For instance, you're not going to be receiving JSON data over email and then putting it into a system manually. Instead, you'll have APIs that handle the JSON formats for you and simply ingest the data.

If you're processing a large volume of data using JSON as the interchange format, why on Earth would you want it to include comments? No service on Earth does this that has any volume of users.

>Also comments in config files are for many things; when file was created, change history, by whom, who to contact with problems, warnings not to edit as it's managed via chef/puppet.

This is not the job of a comment. These go stale and all are available via whatever version control mechanism. However, keep in mind you're talking a very specific edge case in a development environment. Typically these don't matter, at all. If you need comments within the dev system for whatever reason, you can just strip them out. Puppet would obviously have appropriate permissions so no one can simply modify them anyway without knowing they're messing with puppet.

Shipping items, however, should simply have documentation regarding what configurations you product does or does not support.

Re:Douglas Crockford: Why I removed comments from JSON by roel_v on Tuesday May 01, 2012 @05:13AM (#3913556)
Sounds like you're making an awful lot of assumptions about other people's workflows and how they 'should' do things. Have you ever actually worked in a production environment? (no way to ask this without sounding snarky, it's not meant to be mean-spirited)
Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Tuesday May 01, 2012 @09:43AM (#3914248)
I made no assumptions and there is no need to be rude with your incredibly vague question. There are obviously better ways of asking and I'm sure you knew that (otherwise you would have asked a specific question).
Re:Douglas Crockford: Why I removed comments from JSON by roel_v on Tuesday May 01, 2012 @10:18AM (#3914405)
What's vague about the question? I'm not sure how I can be more specific: have you actually ever worked in a production environment? The point being that the things you sum up sound very much like textbook-knowledge and theory, and nothing like something somebody who has actually, you know, worked with software to get things done (as opposed to just playing around) would say.
Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Wednesday May 02, 2012 @02:56PM (#3920574)
>What's vague about the question?

You asked nothing relevant to the conversation. Instead you asked about me ever working in a production environment and nothing more.

That questions accomplishes nothing but being insulting. I hate to sound crass but you're acting like an ass.

If you wish to bring something topical and relevant to the conversation then by all means do so but insulting someone gets nothing accomplished other than trolling...in which case you already won. Congrats.

>The point being that the things you sum up sound very much like textbook-knowledge and theory

No, they don't. Everything I stated is from real-world experience. I cannot fathom what kind of environment you work in where service to service communication includes comments going over the wire. But, as you can see above in my other responses, I've already covered all of these aspects. Nothing theoretical.

Re:Douglas Crockford: Why I removed comments from JSON by nknight on Tuesday May 01, 2012 @12:02AM (#3912942)
I'm forced to wonder from your comments throughout this thread whether you have much real-world development experience, versus having just ingested a bunch of theoretical information on best practices. The things you're dismissing out of hand happen all the time, and while sometimes they're useless, more often they're all the documentation you'll get, and you'll feel exceedingly lucky to get even them.

Your comment about Puppet is especially troubling. Puppet doesn't "have appropriate permissions", it's a root-level tool for managing system state. The files it manages may have all kinds of ownership and permissions, some of which are not ones you can just mess with (e.g. the system will throw up its hands and bomb out if they're wrong), and all of which are still modifiable by anyone with root access. There's no way to differentiate short of comments in the files themselves.

Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Tuesday May 01, 2012 @09:32AM (#3914207)
>I'm forced to wonder from your comments throughout this thread whether you have much real-world development experience, versus having just ingested a bunch of theoretical information on best practices. The things you're dismissing out of hand happen all the time, and while sometimes they're useless, more often they're all the documentation you'll get, and you'll feel exceedingly lucky to get even them.

This is highly arrogant comment. There was no need to be rude. I've been developing and working with actual data for over a decade now. Yes, in the real world sometimes comments are transmitted over the line but I'm sure you can agree that isn't a good idea. Yes, many times you don't get good documentation but you make it sound like that's acceptable and anyone who thinks otherwise doesn't have real-world experience.

In all honestly I would expect comments generated from some odd software packages but it's been an incredibly long time since I've seen data transmissions that contain comments. In environments dealing with petabytes of data you can't afford to send comments with every single file.

As for Puppet, I think you misunderstand my point. Yes, it is a root-level tool. That doesn't mean any user should have the same permissions as Puppet. Why wouldn't you simply place configuration files people shouldn't modify in places where they don't have permission but Puppet does? Honestly, I thought that was standard practice.

Re:Douglas Crockford: Why I removed comments from JSON by nknight on Tuesday May 01, 2012 @01:48PM (#3915543)
You can claim all the experience you want, but your statements belie the truth. JSON is in no way limited to raw data interchange, and the files puppet manages cannot be put off to one side in some magical place where root cannot access them. System administrators will always have access to the files no matter where they are or what permissions you have set, and they need to know that the files are being automatically managed. The system also needs to know where to find the files, you can't start randomly moving /etc/fstab around, for example.
Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Wednesday May 02, 2012 @02:52PM (#3920555)
>You can claim all the experience you want, but your statements belie the truth. JSON is in no way limited to raw data interchange,

I never stated such a thing but that is what it's designed for and the primary use-case for JSON. I would imagine most other cases are edge-cases.

>and the files puppet manages cannot be put off to one side in some magical place where root cannot access them.

No one said to push them off to the "side" or into some "magical place". It's really simple: puppet has permissions to the files, your users do not.

A system administrator worth his salt isn't going to be messing with configuration files any which way and if said administrator has ROOT access then they should already know that's the level where puppet works and they could screw something up.

So I'm not really sure what your point was...

Re:Douglas Crockford: Why I removed comments from JSON by mryan on Tuesday May 01, 2012 @02:53AM (#3913324)
It appears that he is referring to JSON within the limited context of web APIs. The scenarios dismissed as a "very specific edge case in a development environment" appear to crop up all the time when using JSON for something other than APIs - for example, CloudFormation stack templates are written in JSON, and would sorely benefit from some in-line comments.
Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Tuesday May 01, 2012 @09:41AM (#3914241)
>It appears that he is referring to JSON within the limited context of web APIs.

I was referring to JSON as an interchange format, which is what it is.

Arguably Amazon should have chosen something different for templates but I think that's an issue beyond simple comments and outside the scope of the argument. Regardless, it's hard to image anyone thinking it's a good idea to send comments over the wire especially if the end point is some sort of service.

Re:Douglas Crockford: Why I removed comments from JSON by nirvdrum on Monday April 30, 2012 @10:18PM (#3912675)
It's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment.

Note in this case, nothing would be transmitted over the wire. JSON is just being used as a convenient format. Even still, it can be handy to exchange annotated data over the wire.

Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Monday April 30, 2012 @10:36PM (#3912731)
>It's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment.

What happens when you accidentally delete a value you didn't mean to? You would refer to documentation. Honestly all configuration files _should_ be well documented, including postgres so I don't see the issue here. Why would you want to include every single possible option, probably commented out, when you could simply grab the ones you need from the documentation? I would prefer having a lean configuration file that shows exactly what I'm using rather than 400 commented options; that's a MESS to maintain.

>Even still, it can be handy to exchange annotated data over the wire.

I cannot disagree more. It is not useful AT ALL to exchange annotated data. Unless you're using an ad-hoc system (which obviously wouldn't scale), you're going to be handling this through APIs and services that already know and understand the JSON file format. So the only purpose of comments at this stage in the game is using up extra bandwidth.

Re:Douglas Crockford: Why I removed comments from JSON by AlisdairO on Tuesday May 01, 2012 @03:28AM (#3913376)
> You would refer to documentation.

Right, but what if you want to document why you personally are using a particular option, rather than just what an option does? I agree that a lot of the time config comments are unnecessary, but they do have a place.

Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Tuesday May 01, 2012 @09:27AM (#3914189)
That is something that MUST exist in documentation. If you're putting it within the configuration file itself it can go stale or simply deleted one day and you would have no idea what occurred after the fact without looking at a revision history.

I'm a bit puzzled by documentation seems like a bad word around here; it has its place and I'm not suggesting writing up a huge document. It takes only a couple of minutes to drop some text in Word / Google Docs / Wiki / your flavor and put it someplace accessible for your entire team.

Re:Douglas Crockford: Why I removed comments from JSON by AlisdairO on Wednesday May 02, 2012 @05:48AM (#3918260)
Documentation isn't a bad word - I regularly make documents to describe the architecture of my projects, along with their an outline of how to get into the codebase, for example. Comments are also documentation, though, and in this case comments are the right place. If I'm looking at a configuration option and thinking 'That seems a bit odd. Why do we have that set?' I want to be able to see the reasoning right there, not have to hunt through a wiki in the hope that someone has put their reasoning somewhere.

In my experience, comments are less likely to go stale than wiki docs.

Re:Douglas Crockford: Why I removed comments from JSON by nirvdrum on Tuesday May 01, 2012 @10:35AM (#3914496)
I'm not refuting the value of documentation, I'm just acknowledging the referential integrity issues with it. All too frequently I've encountered cases where a config file gets updated but the wiki doesn't. Since all configuration files are version-controlled, I never run into a situation where a file changes and I don't know why (well, discounting bad commit messages). But, a documented wiki wouldn't help in that case anyway. A comment is documentation too ...
Re:Douglas Crockford: Why I removed comments from JSON by nirvdrum on Tuesday May 01, 2012 @07:55AM (#3913887)
I didn't say include every possible option. But it sure is handy when I modify one and there's a nice comment telling me "hey, if you change this, you absolutely must go change this other value too, otherwise all hell is going to break loose." I'm much more apt to screw up the config if I have to look that up every time. That aside, it's really helpful to communicate to other people on the team that "this value is 768 MB because that's roughly 1/2 the total memory on this machine."

Re: transmitting annotated data. All I can say is not every application of JSON is for APIs for mobile devices. When I have a connected gigabit network and gzip data, I may not be that concerned about an extra 50 bytes of annotated data. But, again, that even presupposes that its only application is for computer-to-computer communication. The value in comments are human-to-human.

Re:Douglas Crockford: Why I removed comments from JSON by Yarnage on Tuesday May 01, 2012 @09:24AM (#3914184)
>I'm much more apt to screw up the config if I have to look that up every time. That aside, it's really helpful to communicate to other people on the team that "this value is 768 MB because that's roughly 1/2 the total memory on this machine."

JSON comments would be a short-cut, sure, but that information should be within reach and should NOT only exist within the JSON anyway. So the helpfulness seems really limiting here.

>Re: transmitting annotated data. All I can say is not every application of JSON is for APIs for mobile devices. When I have a connected gigabit network and gzip data, I may not be that concerned about an extra 50 bytes of annotated data. But, again, that even presupposes that its only application is for computer-to-computer communication. The value in comments are human-to-human.

You're right in that the value for comments are human to human; I just cannot picture a scenario where you're actually transmitting data over the wire and including comments. I am not limiting this to mobile device; any service end point should ignore any comments and they will never be seen anyway.

As I mentioned before, if you're ingesting files in a very ad-hoc manner then of course comments could be useful but that's not a typical use-case of JSON. JSON is typically used as an interchange format for end point to end point communication and comments in ANY type of file in that scenario are useless.