Comments in package.json: @comment prefix

[rkristelijn]

What / Why

As a developer you would like to leave comments in the same context as you write code to note down todo's, leave hints for other devs or other reasons. Most of my code allows for this except for package.json, at least, there is no standard. After reading this blog I think this should be a standard, in a way that more people use the same notation and my IDE or VSC highlights comments as a comment.

When

• at code-time

Where

package.json

How

The proposed standard (for now) is that above a specific property in an array, you note down the same property prefixed with @comment<space>.

Current Behavior

• @comment is not a common standard
• if this is done and agreed in this context, I can follow through and talk to IDE's repos

• n/a

Expected Behavior

• @comment is not a common standard

• n/a

Who

• n/a

References

this blog

• n/a

[DanielRuf]

JSON normally does not support that. JSON5 would be an alternative solution.

Personally I don't think this is a good idea in general.

[rkristelijn]

JSON normally does not support that. JSON5 would be an alternative solution.

I've looked into JSON5 for package.json and found this discusion discussing: package.yml and package.js. An example of package.yaml and the package.yaml issue. Also hjson is discussed. I realise I've opened the can of worms again, however I also realise I'm not alone requesting comments in package.json.

I will look into json5 and see if I can make something work. Currently I have no new arguments for this issue/change-request.

Can you elaborate and motivate your thoughts why you think it is not a good idea to support comments?

[ljharb]

JSON already supports comments:

{
  "foo": "the foo field is for storing valuable information",
  "foo": "the real value of foo"
}

[DanielRuf]

JSON already supports comments:

Not native / real comments but a workaround which is also shown in the blogpost which the reporter linked afaik.

[ljharb]

The blog post talks about making parallel keys in a "comments" sub-object. I'm saying that JSON natively allows duplicate keys, so as long as the last one is the actual value, you can use the duplicates for anything you like, including comments.

[DanielRuf]

Your example would throw linting errors in some cases (duplicate key) and could throw parsing errors in a few cases probably.

Douglas Crockford did not add any support for comments in the original specs (only specific JS types) and does not intend to.

[DanielRuf]

As far as I understand the request is very specific (annotation @comment)- or special field.

[DanielRuf]

And how it's displayed in IDEs (differently).

[ljharb]

Anything that errors on duplicate keys in JSON is violating the JSON spec (short of a linter rule that could be disabled, of course). Crockford has not influenced the JSON spec in many years, and TC39 (which does) certainly has no intention of changing it :-)

[DanielRuf]

True. But I would suggest adding HJSON or JSON5 support as this makes more sense (readability, ecosystem support and features) than such a "workaround". Just my opinion.

[DanielRuf]

Can you elaborate and motivate your thoughts why you think it is not a good idea to support comments?

• if this is done and agreed in this context, I can follow through and talk to IDE's repos

That would be a huge effort.

[shawonforhad]

Vv

[shawonforhad]

[iandunn]

Douglas Crockford did not add any support for comments in the original specs (only specific JS types) and does not intend to.

I don't think that's accurate. He said:

A JSON encoder MUST NOT output comments. A JSON decoder MAY accept and ignore comments.

Comments were initially allowed, and were only removed to prevent people from adding parsing directives. There's no reason that decoders can't allow and ignore them, and some do.

npm init shouldn't add any comments, but npm install etc don't need to remove ones that a developer has intentionally added either.

There's lots of potential workarounds, but they all suck in various ways. Developers are always going to want to add comments, and fighting that causes a lot of wasted time and frustration.

Of course, if supporting JSON5 is a more practical solution, that'd be just as good.

[Vadorequest]

I wish we had this for Christmas 2020.

Honestly, whether it's JSON 5 or another standard, it'd be better than what we got at the moment.
Comments are so important in anything non-trivial. I don't understand why JSON5 isn't compatible with package.json file already, it's not like this file is going to be fetched from a browser or something alike. It's only used by node.js and it would be possible to use a JSON5 loader for this particular file in a backward-compatible way.

[ljharb]

The first step would have to be adding native support in node itself for loading another format, so that every tool in the ecosystem could switch to using it to read package.json. Once all of them switched, then it'd be reasonable to suggest npm supporting that format for package manifests.

[TArch64]

Guys, you can use this thing and do something like this (I've tried, it's really works)

{
  "//": [
     "You can add",
     "some multi-line comment",
   ],
  "name": "test",
  "scripts": {
    "//": "or you can use single-line comment"
  },
  "dependencies": {
    "//": {
      "also": "you can add comments in object-style"
    }
  }
}

[snebjorn]

@darcyclarke Please state the reason for closing

[AlexWayfer]

Still no reason for closing…

[AlexWayfer]

I understand that open source is free and here are no debts, but I ask to describe (at least shortly) a reason for such important actions like closing an issue, at least for respect to the community.

[AlexWayfer]

I don't know what to do else, but I can account such action as Code of Conduct violation (I can be wrong). More precisely, "Be respectful" and "providing a friendly, safe and welcoming environment for all". I want to mark that I'm not "spamming, trolling, flaming, baiting, or other attention-stealing behavior", I just see a community activity here, interest in a feature or enhancement, conversation, with respect to maintainers and their decisions, but we want a simple reason (description) for closing (decline?) here. Can we get it for "friendly and welcoming environment"? Who should I tag if @darcyclarke doesn't response for their actions?

[ljharb]

@AlexWayfer theres a few likely reasons. One is that feature requests must go in the RFC repo and not this repo. Another is that npm almost certainly won’t support a format that node itself doesn’t support. Another is that allowing an additional format in published packages would break a ton of tooling and wouldn’t likely be worth the churn.

Before filing an rfc, please check to see if one for this has already been filed and discussed.

[AlexWayfer]

@AlexWayfer theres a few likely reasons. One is that feature requests must go in the RFC repo and not this repo. Another is that npm almost certainly won’t support a format that node itself doesn’t support. Another is that allowing an additional format in published packages would break a ton of tooling and wouldn’t likely be worth the churn.

Before filing an rfc, please check to see if one for this has already been filed and discussed.

OK, thanks. Finally we got some response.

About "a wrong place" — an issue can be transferred to more proper repo.

With the rest things I can agree, we just wanted to clarify this actions and maintainers decisions.