5 ms·

FWIW, I'm well aware of Crockford's rationale, I think it's some of the dumbest rationalization I've heard, and time has shown that it was a giant mistake. Try

FWIW, I'm well aware of Crockford's rationale, I think it's some of the dumbest rationalization I've heard, and time has shown that it was a giant mistake. Trying to prevent programmers from doing something "because they may 'misuse' comments" is asinine to the extreme. This is not like removing a footgun, it's trying to dictate how you think programming should be done. This is particularly hilarious because I've instead seen tons of horribly hacky workarounds for JSON's lack of comments, e.g. "fake" object entries like "__previousKey_comment": "this is a comment for previous key", or even worse, putting two entries with the same key since the second key should "win", and thus making the first entry the comment. As for his second point, "Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser." - just look at the everlasting shit show that is package.json since it can't support comments, because lots of NPM tools actually write to package.json, so there is no guarantee that other tools will be able to read package.json if it includes comments. I think the thing that I hate most about Crockford's rationalization of not having comments is that you have to have your head stuck 10 feet in the sand to pretend that somehow the lack of comments is a good thing with the benefit of hindsight. I guess I could understand if Crockford's position was "Yeah, originally I thought it was better to keep them out because I was concerned about misuse, but now in retrospect to see the much larger problems it causes, and I realize it was a mistake." But instead he just keeps pushing his original crappy opinion on this topic.

mp05 2y ago
@fat is that you?
- hn_throwaway_99 2y ago
  Did you just call me fat ;) I don't know who @fat is, but if he thinks Crockford's rationalization for the lack of comments in JSON is total and complete BS, I like the way he thinks.
  - mp05 2y ago
    https://news.ycombinator.com/item?id=3842713 https://news.ycombinator.com/item?id=3842713 Not sure why all the downvotes? Thought this was a classic.
justmedep 2y ago
I usually just add my comment as an additional field called _comment or something like that
- hn_throwaway_99 2y ago
  Exactly, and that's a crappier workaround. E.g. in lots of places you can't just have willy-nilly, anything-goes key names. An example I think every Node developer can commiserate with is that there isn't really a great way to add comments in the dependencies or devDependencies section in package.json, because those keys need to refer to module names, and that's where I most often want to use comments in package.json. I won't rehash all the details but just take a look at https://stackoverflow.com/questions/14221579/how-do-i-add-comments-to-package-json-for-npm-install https://stackoverflow.com/questions/14221579/how-do-i-add-co... . Unfortunately none of the answers there are very good. In the past I've resorted to doing what https://stackoverflow.com/a/45815391/1075909 https://stackoverflow.com/a/45815391/1075909 does, but that ends up not working very well once you've got a long list of dependencies, because the comment for any particular dependency ends up being far from the entry that specifies the dependency (instead of the line above), so people end up not reading it or forget to update it if that becomes necessary. Yeah, I really, really hate that JSON doesn't have comments :)
- efitz 2y ago
  I have encountered many systems that explicitly disallow “unexpected” JSON elements and such an approach would fail. This is particularly common when using JSON around API-like use cases.
- thayne 2y ago
  So how do you add a comment in the middle of an array?
  - oneeyedpigeon 2y ago
    How do you add a comment in the middle of a keyword in JavaScript?
milch 2y ago
I've also seen parser directives inserted into the keys like `{ "fooBar__datetime": 123456780.0 }`, and many other creative workarounds
- mmis1000 2y ago
  Actually there is a common practice that java or js library used to serialize typed data. They just preserve the key starts with $ for special use So a class A with a double and and an int field will be something like { "$type": "A" "value":{ "a": { "$type": "double", "value": 1 }, "b": { "$type": "int", "value": 2 } } } And what about keys that actually starts with $? You just escape it with special $raw key "$raw": { "$escaped": { "$type": "double", "value" 1 } } It's a bit way too verbose. But given it is just a serialization format inside some library or app, it won't cause too much problems.
leptons 2y ago
When I think of how often and where JSON is used, as a data interchange format for APIs, in the browser, databases, and everywhere else - all the billions of bytes transferred in JSON every second - in all those use cases comments would be pointless and counterproductive and just take up storage space or bandwidth. That's JSON's primary use case in the world. It's only in the very few use cases specifically for programmers where comments would sort of be helpful in JSON, and most of those cases are not really that important to support when there are workarounds - structure your JSON well and you can include the comments as part of the JSON, and then you can even use the comments programmatically should that be useful (which I think is slightly more useful than storing knowledge in a JSON file as a comment). >Trying to prevent programmers from doing something "because they may 'misuse' comments" is asinine to the extreme. Programmers are often their own worst enemies. Some prefer rigid rulesets over less rigid freeform programming. See Typescript vs Javascript. No comments in JSON is just another example of over-rigidification, and some programmers love that. >package.json since it can't support comments, If you're needing to write comments in package.json, maybe you're not approaching package.json correctly? It's really for node things, not your things that you need to write comments about. I'm not even sure why someone would want to write comments in package.json. I get it with comments in other JSON files, but package.json probably should be left for nodejs things.
- hn_throwaway_99 2y ago
  It's hard for me to find a comment where I disagree with literally every sentence, but congrats! 1. So what if JSON is primarily used for data interchange? It's not like allowing comments would somehow make them magically show up on serialized objects. This objection makes 0 sense to me. And heck, tons of other serialization formats (e.g. XML) support comments. Besides, there is a big reason that human-readable serialization formats are so popular - because they're human readable! If you're really worried about size you should be using a binary format anyway. 2. "Rigid rulesets" has nothing to do with Crockford's arguments. It's one thing to prefer a particular type system, or limit functionality if you think it has high potential for misuse. By JSON not having comments all you end up with is worse workarounds, like putting comments in object keys. 3. "I'm not even sure why someone would want to write comments in package.json" To be blunt, then, I can't believe you've ever written any code in a business (i.e. with multiple developers) in the Node/NPM ecosystem. Is it really that hard to wonder why someone would want to comment why they added a particular dependency to their project? The lack of comments in package.json is one of the biggest complaints of this format, and it's certainly not just me, e.g. https://github.com/npm/npm/issues/4482 https://github.com/npm/npm/issues/4482 and https://stackoverflow.com/questions/14221579/how-do-i-add-comments-to-package-json-for-npm-install https://stackoverflow.com/questions/14221579/how-do-i-add-co...
6510 2y ago
I one time by sort of accident coined a config format by parsing todo.txt It was so useful it stuck around for much longer than I had intended to. Rather than comment out stuff it just looks for "=" and ignores everything else. conf = {}; configFile.split('\n').forEach( function(x){ y = x.split(' '); if(y[1]=="=") conf[y[0]] = y[2]; }); Everything is a comment with exception of lines like: speed = 100 km/h weight = 60 kg maxBuffer = 200 chars (between 100 and 300 works best) output: {"speed":100,"weight":60,"maxBuffer":200} It had walls of text with headings and something configurable sprinkled in. Crockford would be screaming. lol
- selcuka 2y ago
  Reminds me of Whitespace [1] where anything but a whitespace is a comment. [1] https://en.wikipedia.org/wiki/Whitespace_(programming_language) https://en.wikipedia.org/wiki/Whitespace_(programming_langua...
oneeyedpigeon 2y ago
I just took a look at an example package.json file and it seemed fine — no 'comments' shoehorned in anywhere, meaningful key names that reduced the need for comments. Do you have an example of a package.json file that would be better if json supported comments?
- Uvix 2y ago
  I don't have an example file on hand, but they would be useful for documenting non-explicit dependencies between packages. e.g. Kendo UI and the corresponding theme packages[1] - neither NPM package depends on the other, but if there's a comment then when seeing a change to one, the developer or a reviewer should know to double-check the other. [1] https://docs.telerik.com/kendo-ui/styles-and-layout/sass-version-compatibility https://docs.telerik.com/kendo-ui/styles-and-layout/sass-ver...
- webstrand 2y ago
  Well not offhand, comments aren't supported so workarounds are used instead. But I would find it very convenient if I could leave comments on dependencies and scripts. Or even various engine requirements. Sure you can write everything in another file or put the comments in the commit message. But out-of-band comments are more easily missed or lost. If the package.json got rewritten by `npm install` you'd lose the comments. Inconvenient, but that's trivial to fix at commit time.

mp05 2y ago

@fat is that you?

hn_throwaway_99 2y ago
Did you just call me fat ;) I don't know who @fat is, but if he thinks Crockford's rationalization for the lack of comments in JSON is total and complete BS, I like the way he thinks.
- mp05 2y ago
  https://news.ycombinator.com/item?id=3842713 https://news.ycombinator.com/item?id=3842713 Not sure why all the downvotes? Thought this was a classic.

justmedep 2y ago

I usually just add my comment as an additional field called _comment or something like that

hn_throwaway_99 2y ago
Exactly, and that's a crappier workaround. E.g. in lots of places you can't just have willy-nilly, anything-goes key names. An example I think every Node developer can commiserate with is that there isn't really a great way to add comments in the dependencies or devDependencies section in package.json, because those keys need to refer to module names, and that's where I most often want to use comments in package.json. I won't rehash all the details but just take a look at https://stackoverflow.com/questions/14221579/how-do-i-add-comments-to-package-json-for-npm-install https://stackoverflow.com/questions/14221579/how-do-i-add-co... . Unfortunately none of the answers there are very good. In the past I've resorted to doing what https://stackoverflow.com/a/45815391/1075909 https://stackoverflow.com/a/45815391/1075909 does, but that ends up not working very well once you've got a long list of dependencies, because the comment for any particular dependency ends up being far from the entry that specifies the dependency (instead of the line above), so people end up not reading it or forget to update it if that becomes necessary. Yeah, I really, really hate that JSON doesn't have comments :)
efitz 2y ago
I have encountered many systems that explicitly disallow “unexpected” JSON elements and such an approach would fail. This is particularly common when using JSON around API-like use cases.
thayne 2y ago
So how do you add a comment in the middle of an array?
- oneeyedpigeon 2y ago
  How do you add a comment in the middle of a keyword in JavaScript?

milch 2y ago

I've also seen parser directives inserted into the keys like `{ "fooBar__datetime": 123456780.0 }`, and many other creative workarounds

mmis1000 2y ago
Actually there is a common practice that java or js library used to serialize typed data. They just preserve the key starts with $ for special use So a class A with a double and and an int field will be something like { "$type": "A" "value":{ "a": { "$type": "double", "value": 1 }, "b": { "$type": "int", "value": 2 } } } And what about keys that actually starts with $? You just escape it with special $raw key "$raw": { "$escaped": { "$type": "double", "value" 1 } } It's a bit way too verbose. But given it is just a serialization format inside some library or app, it won't cause too much problems.

leptons 2y ago

When I think of how often and where JSON is used, as a data interchange format for APIs, in the browser, databases, and everywhere else - all the billions of bytes transferred in JSON every second - in all those use cases comments would be pointless and counterproductive and just take up storage space or bandwidth. That's JSON's primary use case in the world. It's only in the very few use cases specifically for programmers where comments would sort of be helpful in JSON, and most of those cases are not really that important to support when there are workarounds - structure your JSON well and you can include the comments as part of the JSON, and then you can even use the comments programmatically should that be useful (which I think is slightly more useful than storing knowledge in a JSON file as a comment). >Trying to prevent programmers from doing something "because they may 'misuse' comments" is asinine to the extreme. Programmers are often their own worst enemies. Some prefer rigid rulesets over less rigid freeform programming. See Typescript vs Javascript. No comments in JSON is just another example of over-rigidification, and some programmers love that. >package.json since it can't support comments, If you're needing to write comments in package.json, maybe you're not approaching package.json correctly? It's really for node things, not your things that you need to write comments about. I'm not even sure why someone would want to write comments in package.json. I get it with comments in other JSON files, but package.json probably should be left for nodejs things.

hn_throwaway_99 2y ago
It's hard for me to find a comment where I disagree with literally every sentence, but congrats! 1. So what if JSON is primarily used for data interchange? It's not like allowing comments would somehow make them magically show up on serialized objects. This objection makes 0 sense to me. And heck, tons of other serialization formats (e.g. XML) support comments. Besides, there is a big reason that human-readable serialization formats are so popular - because they're human readable! If you're really worried about size you should be using a binary format anyway. 2. "Rigid rulesets" has nothing to do with Crockford's arguments. It's one thing to prefer a particular type system, or limit functionality if you think it has high potential for misuse. By JSON not having comments all you end up with is worse workarounds, like putting comments in object keys. 3. "I'm not even sure why someone would want to write comments in package.json" To be blunt, then, I can't believe you've ever written any code in a business (i.e. with multiple developers) in the Node/NPM ecosystem. Is it really that hard to wonder why someone would want to comment why they added a particular dependency to their project? The lack of comments in package.json is one of the biggest complaints of this format, and it's certainly not just me, e.g. https://github.com/npm/npm/issues/4482 https://github.com/npm/npm/issues/4482 and https://stackoverflow.com/questions/14221579/how-do-i-add-comments-to-package-json-for-npm-install https://stackoverflow.com/questions/14221579/how-do-i-add-co...

6510 2y ago

I one time by sort of accident coined a config format by parsing todo.txt It was so useful it stuck around for much longer than I had intended to. Rather than comment out stuff it just looks for "=" and ignores everything else. conf = {}; configFile.split('\n').forEach( function(x){ y = x.split(' '); if(y[1]=="=") conf[y[0]] = y[2]; }); Everything is a comment with exception of lines like: speed = 100 km/h weight = 60 kg maxBuffer = 200 chars (between 100 and 300 works best) output: {"speed":100,"weight":60,"maxBuffer":200} It had walls of text with headings and something configurable sprinkled in. Crockford would be screaming. lol

selcuka 2y ago
Reminds me of Whitespace [1] where anything but a whitespace is a comment. [1] https://en.wikipedia.org/wiki/Whitespace_(programming_language) https://en.wikipedia.org/wiki/Whitespace_(programming_langua...

oneeyedpigeon 2y ago

I just took a look at an example package.json file and it seemed fine — no 'comments' shoehorned in anywhere, meaningful key names that reduced the need for comments. Do you have an example of a package.json file that would be better if json supported comments?

Uvix 2y ago
I don't have an example file on hand, but they would be useful for documenting non-explicit dependencies between packages. e.g. Kendo UI and the corresponding theme packages[1] - neither NPM package depends on the other, but if there's a comment then when seeing a change to one, the developer or a reviewer should know to double-check the other. [1] https://docs.telerik.com/kendo-ui/styles-and-layout/sass-version-compatibility https://docs.telerik.com/kendo-ui/styles-and-layout/sass-ver...
webstrand 2y ago
Well not offhand, comments aren't supported so workarounds are used instead. But I would find it very convenient if I could leave comments on dependencies and scripts. Or even various engine requirements. Sure you can write everything in another file or put the comments in the commit message. But out-of-band comments are more easily missed or lost. If the package.json got rewritten by `npm install` you'd lose the comments. Inconvenient, but that's trivial to fix at commit time.