6 ms·

A killer feature of TOML compared to JSON is that it allows comments. A config file without comments and examples ain't great. I found the double square bracket

A killer feature of TOML compared to JSON is that it allows comments. A config file without comments and examples ain't great. I found the double square bracket syntax useful and understandable. Agreed it's not obviously .INI or perfectly elegant but it certainly works and has its use-cases. Anyways, thank you @mojombo!

alokitr 8y ago
> I found the double square bracket syntax useful and understandable Really? I had kind of the inverse reaction to it. Indeed useful, but definitely not understandable
- adrusi 8y ago
  It's kind of similar to the syntax of uri query strings and the php syntax for appending to arrays, in that an extra pair of square brackets indicates appending: In php: $a[] = 1; $a[] = 2; # $a == array(1, 2) In URIs: http://example.org/?a[]=1&b[]=2 Compare to TOML [[a]] item = 1 [[a]] item = 2
  - majewsky 8y ago
    That URI syntax is just a convention used by some web frameworks. You can just as well write https://example.org?foo=bar&foo=baz
    - TimothyBJacobs 8y ago
      Not for PHP at least, maybe others, the last query arg will win.
kolpa 8y ago
Json allows comments, but they have to be in string fields of an object so they survive reserialization.
- __david__ 8y ago
  So then… not actually comments at all? A nice config parser will error out or at least warn loudly when encountering an unknown parameter. This helps prevent typos.
oblong 8y ago
JSON is a serialization protocol not a config file format idiot.
spondyl 8y ago
JSON used to support comments but they started being used for unintended things like parsing directives.[0] It is apparently possible to include, and then remove them before usage apparently but I've never tried. [0]: https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaGSr https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaG...
- suby 8y ago
  I'm personally doing something similar in a C++ project that I'm working on. I designate comments with a //. When I load the JSON file, I go line by line removing comments as I find them. Once the file is parsed you can feed it into any regular JSON parser (personally I'm a fan of https://github.com/nlohmann/json https://github.com/nlohmann/json). Using JSMin would have been a much better idea. At this point though the only downside is that I haven't yet done this for saving JSON. It's a harder problem but I don't see why it wouldn't also be doable. edit: Apparently this library allows you to have comments, and will even preserve them when saving the JSON file. https://github.com/open-source-parsers/jsoncpp https://github.com/open-source-parsers/jsoncpp
  - frumiousirc 8y ago
    You could use libjsonnet++ instead of a custom reader to gain the extension of using comments. Of course, Jsonnet is a gateway drug to a much more sophisticated superset of JSON.
  - spiralx 8y ago
    There's the JSON5 format that supports comments, there are libraries available for parsing and encoding it.
mlthoughts2018 8y ago
I used to feel this way, and also used to be frustrated about multi-line strings in JSON. With years of experience now, though, I actually appreciate JSON omitting these features. Config files should absolutely not have or need comments. If you need them directly in the config file, something is wrong. Applications should document their default settings in a different way, preferably in a README or generated documentation that also explains how to use environment variables to override the defaults. That sort of separate companion doc is the right place for notes about defaults or "why" certain config values exist in the file. The same is true for using JSON to store parameter files, etc. It's actually quite important to keep metadata about the config / params / etc. specifically out of those files, so that they are absolutely nothing but value files. Information about why a file contains those values belongs elsewhere, and it's an anti-pattern IMO to rely on comments in the config / param file.
- Waterluvian 8y ago
  I have never disagreed with someone more than I do now. =) Config absolutely needs comments. Context is everything. Comments allow me to explain to other humans why the config is the way it is. Dumping that out to a separate file is begging for it to fall out of sync when there's no comment instructing anyone to go and update the other file. Plus that's just kind of silly.
  - dmurray 8y ago
    I would even say config needs comments more than code does. Code can be self-documenting: by using good variable and function names, splitting or combining lines of code, or re-ordering blocks of code you can often make the intent of the code clearer without adding explicit comments. If you do something unexpected in a config file, it likely just shows as setting some name to a magic number or a magic string.
    - zbruhnke 8y ago
      This ... so many things about configuration decisions that make sense at a point in time but can change with versions of a library, OS, server etc. In past lives I have had to hack around so many different things to make something work they way I intended that I knew there would likely be a better solution to at some point. As we get closer to things like infrastructure as code and configuration as code being the norm I would like to take this comment to remind people there is no such thing as self commenting code! Even if this configuration should be “obvious” given constraints today when someone comes back to this months or years from now it’s likely some of those constraints could have changed or been removed completely - ignoring this is how you end up not changing things out of fear that something will break without real understanding. Comments are almost never a problem unless they’re not updated when significant changes are made
mojombo 8y ago
You're welcome, really glad you like it, and good to know the double square brackets make sense to you! It does seem to be a bit polarizing, so we'll keep working on something even better.
ErikAugust 8y ago
{ “_comment”: “The comment goes here!”, “name”: “foo” }
- Rotten194 8y ago
  So now your comments are flowing through infrastructure wasting bandwidth and possibly leaking internal configuration details?
  - mateuszf 8y ago
    And maybe even breaking code which doesn't what to do with these fields.
  - ErikAugust 8y ago
    Parse private properties in the config files in your build process, if paranoid. I don’t have use cases where I’m sending the full contents of a config across the network. Each property in a config would be explicitly referenced in the application. And it’s not like there isn’t any potential problems with some YAML or TOML library you import. Rails Yaml comes to mind.

alokitr 8y ago

> I found the double square bracket syntax useful and understandable Really? I had kind of the inverse reaction to it. Indeed useful, but definitely not understandable

adrusi 8y ago
It's kind of similar to the syntax of uri query strings and the php syntax for appending to arrays, in that an extra pair of square brackets indicates appending: In php: $a[] = 1; $a[] = 2; # $a == array(1, 2) In URIs: http://example.org/?a[]=1&b[]=2 Compare to TOML [[a]] item = 1 [[a]] item = 2
- majewsky 8y ago
  That URI syntax is just a convention used by some web frameworks. You can just as well write https://example.org?foo=bar&foo=baz
  - TimothyBJacobs 8y ago
    Not for PHP at least, maybe others, the last query arg will win.

kolpa 8y ago

Json allows comments, but they have to be in string fields of an object so they survive reserialization.

__david__ 8y ago
So then… not actually comments at all? A nice config parser will error out or at least warn loudly when encountering an unknown parameter. This helps prevent typos.

oblong 8y ago

JSON is a serialization protocol not a config file format idiot.

spondyl 8y ago

JSON used to support comments but they started being used for unintended things like parsing directives.[0] It is apparently possible to include, and then remove them before usage apparently but I've never tried. [0]: https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaGSr https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaG...

suby 8y ago
I'm personally doing something similar in a C++ project that I'm working on. I designate comments with a //. When I load the JSON file, I go line by line removing comments as I find them. Once the file is parsed you can feed it into any regular JSON parser (personally I'm a fan of https://github.com/nlohmann/json https://github.com/nlohmann/json). Using JSMin would have been a much better idea. At this point though the only downside is that I haven't yet done this for saving JSON. It's a harder problem but I don't see why it wouldn't also be doable. edit: Apparently this library allows you to have comments, and will even preserve them when saving the JSON file. https://github.com/open-source-parsers/jsoncpp https://github.com/open-source-parsers/jsoncpp
- frumiousirc 8y ago
  You could use libjsonnet++ instead of a custom reader to gain the extension of using comments. Of course, Jsonnet is a gateway drug to a much more sophisticated superset of JSON.
- spiralx 8y ago
  There's the JSON5 format that supports comments, there are libraries available for parsing and encoding it.

mlthoughts2018 8y ago

I used to feel this way, and also used to be frustrated about multi-line strings in JSON. With years of experience now, though, I actually appreciate JSON omitting these features. Config files should absolutely not have or need comments. If you need them directly in the config file, something is wrong. Applications should document their default settings in a different way, preferably in a README or generated documentation that also explains how to use environment variables to override the defaults. That sort of separate companion doc is the right place for notes about defaults or "why" certain config values exist in the file. The same is true for using JSON to store parameter files, etc. It's actually quite important to keep metadata about the config / params / etc. specifically out of those files, so that they are absolutely nothing but value files. Information about why a file contains those values belongs elsewhere, and it's an anti-pattern IMO to rely on comments in the config / param file.

Waterluvian 8y ago
I have never disagreed with someone more than I do now. =) Config absolutely needs comments. Context is everything. Comments allow me to explain to other humans why the config is the way it is. Dumping that out to a separate file is begging for it to fall out of sync when there's no comment instructing anyone to go and update the other file. Plus that's just kind of silly.
- dmurray 8y ago
  I would even say config needs comments more than code does. Code can be self-documenting: by using good variable and function names, splitting or combining lines of code, or re-ordering blocks of code you can often make the intent of the code clearer without adding explicit comments. If you do something unexpected in a config file, it likely just shows as setting some name to a magic number or a magic string.
  - zbruhnke 8y ago
    This ... so many things about configuration decisions that make sense at a point in time but can change with versions of a library, OS, server etc. In past lives I have had to hack around so many different things to make something work they way I intended that I knew there would likely be a better solution to at some point. As we get closer to things like infrastructure as code and configuration as code being the norm I would like to take this comment to remind people there is no such thing as self commenting code! Even if this configuration should be “obvious” given constraints today when someone comes back to this months or years from now it’s likely some of those constraints could have changed or been removed completely - ignoring this is how you end up not changing things out of fear that something will break without real understanding. Comments are almost never a problem unless they’re not updated when significant changes are made

mojombo 8y ago

You're welcome, really glad you like it, and good to know the double square brackets make sense to you! It does seem to be a bit polarizing, so we'll keep working on something even better.

ErikAugust 8y ago

{ “_comment”: “The comment goes here!”, “name”: “foo” }

Rotten194 8y ago
So now your comments are flowing through infrastructure wasting bandwidth and possibly leaking internal configuration details?
- mateuszf 8y ago
  And maybe even breaking code which doesn't what to do with these fields.
- ErikAugust 8y ago
  Parse private properties in the config files in your build process, if paranoid. I don’t have use cases where I’m sending the full contents of a config across the network. Each property in a config would be explicitly referenced in the application. And it’s not like there isn’t any potential problems with some YAML or TOML library you import. Rails Yaml comes to mind.