Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Comments in package.json: @comment prefix #677

Closed
rkristelijn opened this issue Jan 10, 2020 · 23 comments
Closed

Comments in package.json: @comment prefix #677

rkristelijn opened this issue Jan 10, 2020 · 23 comments

Comments

@rkristelijn
Copy link

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
Copy link

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
Copy link
Author

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
Copy link
Contributor

ljharb commented Jan 14, 2020

JSON already supports comments:

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

@DanielRuf
Copy link

JSON already supports comments:

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

@ljharb
Copy link
Contributor

ljharb commented Jan 14, 2020

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
Copy link

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
Copy link

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

@DanielRuf
Copy link

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

@ljharb
Copy link
Contributor

ljharb commented Jan 14, 2020

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
Copy link

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
Copy link

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
Copy link

Vv

@shawonforhad
Copy link

Social-Icon

@iandunn
Copy link

iandunn commented Feb 6, 2020

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
Copy link

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
Copy link
Contributor

ljharb commented Oct 27, 2020

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
Copy link

TArch64 commented Mar 23, 2021

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
Copy link

@darcyclarke Please state the reason for closing

@AlexWayfer
Copy link

Still no reason for closing…

@AlexWayfer
Copy link

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
Copy link

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
Copy link
Contributor

ljharb commented May 11, 2021

@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
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

10 participants