Hacker News Reader

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

Reminds me of Whitespace [1] where anything but a whitespace is a comment.

[1] https://en.wikipedia.org/wiki/Whitespace_(programming_langua...

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

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.

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-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 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 :)

So how do you add a comment in the middle of an array?

How do you add a comment in the middle of a keyword in JavaScript?

I often want to comment individual array values to give more context or describe provenance. I don't think I've ever wanted to add a comment in the middle of a keyword.

These two are not remotely the same thing. You can have an array declared on multiple lines and add a comment to specific values. Or even inline with the value /* */.

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

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.

@fat is that you?

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.

https://news.ycombinator.com/item?id=3842713

Not sure why all the downvotes? Thought this was a classic.

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.

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 and https://stackoverflow.com/questions/14221579/how-do-i-add-co...

3. So when that dependency gets removed by npm uninstall how should that comment be handled? You know that in business we just would end up with a bunch of dead comments in the package.json - is that really a better alternative than just using Ctrl+f to find where the dependency is used?

> comment why they added a particular dependency to their project

Surely that's what the commit message is for? I mean, I get that it's more convenient to have the comment right there in the file, but that should be balanced against the downsides: having to maintain the comment, making the file larger and more awkward to read, etc.

Your rationale could apply to all comments in general. Hey, just have folks scour through the commit messages instead!

Yes, I still think a commit message is important, but it absolutely does not take the place of a comment. Suppose you'd like to do something like this:

    // DO NOT change to latest version. MUST pin to version 1.2.3 because
    // 1.2.4 includes a subtle bug that doesn't work with our version of
    // the zed library. We have an open issue on zed, see
    // https://github.com/zed/zed/issues/1234.
    // Once that is fixed, we can upgrade.
    "foobar": "1.2.3"

There is zero chance that comment is going to be seen if its just in a commit message, furthermore you should never depend on git blame showing a particular comment because it's easy for later commits to overwrite it due to simple things like formatting changes, etc. Yes, in that example case there should be tests too, but IMO the primary purpose for comments is to highlight issues and concerns that aren't immediately apparent just by reading the code.

I simply cannot think of another file format that is used for configs that doesn't support comments.

>There is zero chance that comment is going to be seen if its just in a commit message,

I never suggested using a commit message, there are plenty of other ways to document these things and I'll leave that up to the user to figure out.

So now you've written this tome of a comment in package.json. What happens the next time someone installs a package using npm install? package.json gets rewritten, that's what. Your comment will be gone. I suppose you expect npm to somehow use AI to guess at how to rewrite package.json so it can put your comments in the correct places??

And expecting someone to read package.json before updating or installing a library is just as useful as putting it in a commit message. If you really need to be careful about dependency versioning, you better have more safeguards in place than just a comment in package.json.

>I simply cannot think of another file format that is used for configs that doesn't support comments.

I mostly see configs created as .js or .ts files, where comments are allowed. Not package.json. Never package.json, because package.json is guaranteed to be rewritten regularly. But maybe you missed that part of your bootcamp class? Yes, .js files can be used as "config". It's been done in plenty of projects. It isn't the end of the world. JSON also isn't solely used for configs or data that needs comments, in fact the majority of use cases in the world for JSON won't need any comments at all so writing comments in package.json is kind of an edge-case.

>I simply cannot think of another file format that is used for configs that doesn't support comments.

JSON isn't only a config file format. It's primary use is data transfer.

> I never suggested using a commit message, there are plenty of other ways to document these things and I'll leave that up to the user to figure out.

Dude, I think you're lost, in more ways than one. I was directly responding to a comment that stated "Surely that's what the commit message is for?"

For the rest of your comment, at this point I'd rather have an argument with a dining room table. No shit you can't have comments in package.json now, that's the entire reason that issue https://github.com/npm/npm/issues/4482 is unfixable. If JSON supported comments from the beginning, then tooling would have to respect that, just like the bajillion other config file formats that support tooling that updates the config file programmatically.

>The lack of comments in package.json is one of the biggest complaints of this format, and it's certainly not just me

Well then you and plenty of other people have some wrong ideas about package.json. That isn't surprising.

package.json gets rewritten for all kinds of things, which is not really compatible with adding comments wherever you want. Adding "why this dependency is here" comments may seem like a good idea to add to package.json, but you're kind of missing the point. If you need that level of documentation, trying to shoehorn it into package.json is just the wrong place for it. Soon enough your package.json looks like a graffiti wall.

>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.

Then you'll be astonished that I have been working with nodejs for about 14 years professionally. Sure I have wanted to put comments into package.json, but I was naive and now I'm fine not doing that. I haven't wanted to in many years. I document things in other ways and it has served us all very well. YMMV.

> if you need that level of documentation, trying to shoehorn it into package.json is just the wrong place for it. Soon enough your package.json looks like a graffiti wall.

So the right place is to make a graffiti out of another place, instead of in the place where people actually declare the dependencies?

I find it bizarre when people believe in one true way of doing things. I mean, you can declare your dependencies how you like, but if others do it differently, then they're clueless?

You're clueless if you think adding comments to package.json - a file that regularly gets rewritten - is anything but an exercise in futility. Any time you run "npm install [whatever]" you are rewriting package.json. How exactly do you expect to maintain your random comments in this case? You expect nodejs to understand how comments are being written in package.json and not mess that up? You don't seem to understand how npm or package.json works.

This is the silliest of circular logic. Of course you can't add comments to package.json, so tools can do whatever they want to the file. The fact that tools can rewrite parts of it doesn't mean they should just be able to do whatever they want. Literally every other single other config file format supports comments, and I have never seen a problem with tooling on those files due to the presence of comments.

> but I was naive and now I'm fine not doing that

Either https://en.wikipedia.org/wiki/Learned_helplessness or https://en.wikipedia.org/wiki/Normalization_of_deviance

Nice try, but no.

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?

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-ver...

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.