3 ms·

> 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

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

hn_throwaway_99 2y ago
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.
- leptons 2y ago
  >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.
  - hn_throwaway_99 2y ago
    > 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 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.

hn_throwaway_99 2y ago

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.

leptons 2y ago
>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.
- hn_throwaway_99 2y ago
  > 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 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.