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.