7 ms·

This makes sense to me. JSON is designed to simply hold data so there shouldn't need to be any comments. If it's related to configuration then there should be

by Yarnage 14y ago

This makes sense to me. JSON is designed to simply hold data so there shouldn't need to be any comments. If it's related to configuration then there should be documentation regarding what is and isn't supported. If it's simply data you're sending across the wire then there should be documentation somewhere; you wouldn't want to waste bandwidth transmitting comments.

nirvdrum 14y ago
It's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment. Note in this case, nothing would be transmitted over the wire. JSON is just being used as a convenient format. Even still, it can be handy to exchange annotated data over the wire.
- Yarnage 14y ago
  >It's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment. What happens when you accidentally delete a value you didn't mean to? You would refer to documentation. Honestly all configuration files _should_ be well documented, including postgres so I don't see the issue here. Why would you want to include every single possible option, probably commented out, when you could simply grab the ones you need from the documentation? I would prefer having a lean configuration file that shows exactly what I'm using rather than 400 commented options; that's a MESS to maintain. >Even still, it can be handy to exchange annotated data over the wire. I cannot disagree more. It is not useful AT ALL to exchange annotated data. Unless you're using an ad-hoc system (which obviously wouldn't scale), you're going to be handling this through APIs and services that already know and understand the JSON file format. So the only purpose of comments at this stage in the game is using up extra bandwidth.
  - AlisdairO 14y ago
    > You would refer to documentation. Right, but what if you want to document why you personally are using a particular option, rather than just what an option does? I agree that a lot of the time config comments are unnecessary, but they do have a place.
    - Yarnage 14y ago
      That is something that MUST exist in documentation. If you're putting it within the configuration file itself it can go stale or simply deleted one day and you would have no idea what occurred after the fact without looking at a revision history. I'm a bit puzzled by documentation seems like a bad word around here; it has its place and I'm not suggesting writing up a huge document. It takes only a couple of minutes to drop some text in Word / Google Docs / Wiki / your flavor and put it someplace accessible for your entire team.
      - nirvdrum 14y ago
        I'm not refuting the value of documentation, I'm just acknowledging the referential integrity issues with it. All too frequently I've encountered cases where a config file gets updated but the wiki doesn't. Since all configuration files are version-controlled, I never run into a situation where a file changes and I don't know why (well, discounting bad commit messages). But, a documented wiki wouldn't help in that case anyway. A comment is documentation too ...
      - AlisdairO 14y ago
        Documentation isn't a bad word - I regularly make documents to describe the architecture of my projects, along with their an outline of how to get into the codebase, for example. Comments are also documentation, though, and in this case comments are the right place. If I'm looking at a configuration option and thinking 'That seems a bit odd. Why do we have that set?' I want to be able to see the reasoning right there, not have to hunt through a wiki in the hope that someone has put their reasoning somewhere. In my experience, comments are less likely to go stale than wiki docs.
  - 14y ago
njharman 14y ago
> simply hold data so there shouldn't need to be any comments. How does that follow? Usually "data", 5.23423, needs commenting more than most. What the hell is that? Why 5 decimal places? Also comments in config files are for many things; when file was created, change history, by whom, who to contact with problems, warnings not to edit as it's managed via chef/puppet.
- Yarnage 14y ago
  >How does that follow? Usually "data", 5.23423, needs commenting more than most. What the hell is that? Why 5 decimal places? You would already know the answer before seeing the JSON file so I'm not sure why you care. For instance, you're not going to be receiving JSON data over email and then putting it into a system manually. Instead, you'll have APIs that handle the JSON formats for you and simply ingest the data. If you're processing a large volume of data using JSON as the interchange format, why on Earth would you want it to include comments? No service on Earth does this that has any volume of users. >Also comments in config files are for many things; when file was created, change history, by whom, who to contact with problems, warnings not to edit as it's managed via chef/puppet. This is not the job of a comment. These go stale and all are available via whatever version control mechanism. However, keep in mind you're talking a very specific edge case in a development environment. Typically these don't matter, at all. If you need comments within the dev system for whatever reason, you can just strip them out. Puppet would obviously have appropriate permissions so no one can simply modify them anyway without knowing they're messing with puppet. Shipping items, however, should simply have documentation regarding what configurations you product does or does not support.
  - nknight 14y ago
    I'm forced to wonder from your comments throughout this thread whether you have much real-world development experience, versus having just ingested a bunch of theoretical information on best practices. The things you're dismissing out of hand happen all the time, and while sometimes they're useless, more often they're all the documentation you'll get, and you'll feel exceedingly lucky to get even them. Your comment about Puppet is especially troubling. Puppet doesn't "have appropriate permissions", it's a root-level tool for managing system state. The files it manages may have all kinds of ownership and permissions, some of which are not ones you can just mess with (e.g. the system will throw up its hands and bomb out if they're wrong), and all of which are still modifiable by anyone with root access. There's no way to differentiate short of comments in the files themselves.

by Yarnage 14y ago

nirvdrum 14y ago

It's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment. Note in this case, nothing would be transmitted over the wire. JSON is just being used as a convenient format. Even still, it can be handy to exchange annotated data over the wire.

Yarnage 14y ago
>It's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment. What happens when you accidentally delete a value you didn't mean to? You would refer to documentation. Honestly all configuration files _should_ be well documented, including postgres so I don't see the issue here. Why would you want to include every single possible option, probably commented out, when you could simply grab the ones you need from the documentation? I would prefer having a lean configuration file that shows exactly what I'm using rather than 400 commented options; that's a MESS to maintain. >Even still, it can be handy to exchange annotated data over the wire. I cannot disagree more. It is not useful AT ALL to exchange annotated data. Unless you're using an ad-hoc system (which obviously wouldn't scale), you're going to be handling this through APIs and services that already know and understand the JSON file format. So the only purpose of comments at this stage in the game is using up extra bandwidth.
- AlisdairO 14y ago
  > You would refer to documentation. Right, but what if you want to document why you personally are using a particular option, rather than just what an option does? I agree that a lot of the time config comments are unnecessary, but they do have a place.
  - Yarnage 14y ago
    That is something that MUST exist in documentation. If you're putting it within the configuration file itself it can go stale or simply deleted one day and you would have no idea what occurred after the fact without looking at a revision history. I'm a bit puzzled by documentation seems like a bad word around here; it has its place and I'm not suggesting writing up a huge document. It takes only a couple of minutes to drop some text in Word / Google Docs / Wiki / your flavor and put it someplace accessible for your entire team.
    - nirvdrum 14y ago
      I'm not refuting the value of documentation, I'm just acknowledging the referential integrity issues with it. All too frequently I've encountered cases where a config file gets updated but the wiki doesn't. Since all configuration files are version-controlled, I never run into a situation where a file changes and I don't know why (well, discounting bad commit messages). But, a documented wiki wouldn't help in that case anyway. A comment is documentation too ...
    - AlisdairO 14y ago
      Documentation isn't a bad word - I regularly make documents to describe the architecture of my projects, along with their an outline of how to get into the codebase, for example. Comments are also documentation, though, and in this case comments are the right place. If I'm looking at a configuration option and thinking 'That seems a bit odd. Why do we have that set?' I want to be able to see the reasoning right there, not have to hunt through a wiki in the hope that someone has put their reasoning somewhere. In my experience, comments are less likely to go stale than wiki docs.
- 14y ago

njharman 14y ago

> simply hold data so there shouldn't need to be any comments. How does that follow? Usually "data", 5.23423, needs commenting more than most. What the hell is that? Why 5 decimal places? Also comments in config files are for many things; when file was created, change history, by whom, who to contact with problems, warnings not to edit as it's managed via chef/puppet.

Yarnage 14y ago
>How does that follow? Usually "data", 5.23423, needs commenting more than most. What the hell is that? Why 5 decimal places? You would already know the answer before seeing the JSON file so I'm not sure why you care. For instance, you're not going to be receiving JSON data over email and then putting it into a system manually. Instead, you'll have APIs that handle the JSON formats for you and simply ingest the data. If you're processing a large volume of data using JSON as the interchange format, why on Earth would you want it to include comments? No service on Earth does this that has any volume of users. >Also comments in config files are for many things; when file was created, change history, by whom, who to contact with problems, warnings not to edit as it's managed via chef/puppet. This is not the job of a comment. These go stale and all are available via whatever version control mechanism. However, keep in mind you're talking a very specific edge case in a development environment. Typically these don't matter, at all. If you need comments within the dev system for whatever reason, you can just strip them out. Puppet would obviously have appropriate permissions so no one can simply modify them anyway without knowing they're messing with puppet. Shipping items, however, should simply have documentation regarding what configurations you product does or does not support.
- nknight 14y ago
  I'm forced to wonder from your comments throughout this thread whether you have much real-world development experience, versus having just ingested a bunch of theoretical information on best practices. The things you're dismissing out of hand happen all the time, and while sometimes they're useless, more often they're all the documentation you'll get, and you'll feel exceedingly lucky to get even them. Your comment about Puppet is especially troubling. Puppet doesn't "have appropriate permissions", it's a root-level tool for managing system state. The files it manages may have all kinds of ownership and permissions, some of which are not ones you can just mess with (e.g. the system will throw up its hands and bomb out if they're wrong), and all of which are still modifiable by anyone with root access. There's no way to differentiate short of comments in the files themselves.