Hacker News Reader

Comment by mojombo | Hacker News Reader

Hey, Tom here (creator of TOML). Fun to see TOML on HN again! Since I first wrote a (mostly) joke proposal for TOML 5 years ago, TOML has been adopted by a number of prominent projects such as Cargo, Hugo, Pipenv, and others.

TOML is especially well suited for projects that need a simple configuration file that maps unambiguously to a hash table. There are still some weaknesses in TOML that make it non-optimal for large, complex config, but I'm hoping to address that in a later version of the spec (perhaps 2.0).

Happy to answer any questions you all have about TOML!

View on HN

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!

> 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

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

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

Not for PHP at least, maybe others, the last query arg will win.

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

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.

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.

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.

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.

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

I definitely add way more comments to my projects' default config files than I do to my actual codebase, if we're talking total number of comments.

I disagree. It’s an anti-pattern. For example, if you’re writing an application that loads a default config file to populate parameters at run time, then the software module that loads from the default file is the correct place to document it, because the meaning of defaults is relevant to that source code, not at all to someone reading the parameter file itself. A parameter file is just some blob of stuff.

I agree context is everything, and that’s why it’s a bad idea to embed usage info or instructions about the contents or meaning of a parameter file into that very file.

Somewhere else, something has to choose to load that file, and that is where the documentation belongs (in addition to readable, separate artifacts that are generated from the file).

For example, suppose you need to rewrite the parameter file from YAML to Toml, or you need to add a new layer of nesting and some post-processing logic at load time.

The meaning of these things has no context inside the parameter file itself. It only has meaning at the point some other system consumes it. Another system could consume the exact same file and choose to interpret all the parameters with different meanings in that program, regardless of what any comments says in the param file.

I very much disagreed with you two comments up, but this more fleshed out response actually makes a lot of sense. You just moved me from "I'm going to add a build rule that strips comments from all my JSON files so that I can have comments in my configs" to "The next time I want comments in JSON, I'm going to see if what mlthoughts2018 said makes sense in this case. Do I really need to comment this JSON file, or would it be better to put the comments somewhere else instead?"

We'll see how it goes!

Cheers

Maybe that makes sense for the app you are writing that is only consumed by others at your company, but if I'm installing your app from a package manager I absolutely do not want to have to read the config loading source code to figure out what all the parameters do. And even if the docs are nicely described in a man page and not in config file comments, I absolutely want to be able to comment on particular parameter changes ("# had to up foo to 18 because bar was frobbing baz at to high a rate").

Even if you use configuration management it's still nice to be able to comment things in config files since they show up both in the source and in the output files, which is very helpful when debugging.

I specifically meant that comments aren’t a good idea in config files when the config files are distributed to any end users as part of some app or package installation.

> “And even if the docs are nicely described in a man page and not in config file comments, I absolutely want to be able to comment on particular parameter changes ("# had to up foo to 18 because bar was frobbing baz at to high a rate").”

This is the exact anti-pattern that happens as a result of relying on comments in the config file. Your goal of adding that comment about why you changed foo directly in the config file is dangerous and is a very bad practice.

Instead, whatever config file it is that you are modifying (whether for third parties to consume or just for own local Postgres or video game or anything), that file should be turned into a proper package. Place it in a version control repo, and readme and usage documentation for the “why” of the parameter values, and make a tool so that if the end user wants that exact config file, they can “install” it.

For any customized overrides of single settings at run time (so specifically not changes to a config file), it should happen via the end user overriding ENV variables, not mucking around in config files and trusting ad hoc comments found inside them.

You're talking about comments that document the semantics of fields in a config file. Most other people here are talking about comments that describe why the _specific values_ present in a _specific file_ were chosen.

Whether documenting semantics of fields belongs in a config file or code (I say both!), it simply doesn't make any sense to say that comments about why specific values in specific files are the way they are belong in the code that parses them. (How can the parsing code have knowledge of all config files out there?)

No, I am talking specifically about comments or documents that explain the "why" behind parameter choices. For canonical defaults that are shipped with an app, this should be documented in a user guide and in the appropriate parts of the source code, not inside the config file (which most users would never care to read, and which would be worse to read for most developers who might care or change it).

For local config files that are not shipped with the package, they should still be source controlled in a separate repo (yes, even if you personally are the only one using it, like your local Postgres configuration or something), and you should use a good practice to 'deploy' any changes to your config from the repo into the actual location where the application can recognize that config -- meaning that documentation about the "why" of the parameters once again should absolutely not be embedded inside the config file itself.

If they're not in the config file, where exactly are they then?

A text file sitting next to the config file? I can't see any benefit to that arrangement over just using comments in the file.

Comments that exist in the file in the repo but get stripped out by the deploy process? Again, there seems to be no point to doing this.

Commit log messages? I agree commit logs can sometimes be valuable to see the context of a change, but 1) they're fundamentally about documenting _changes_, not the contents themselves, and 2) the UI is really clunky: git blame, find the line you want context for, then git show on that commit.

>I agree context is everything, and that’s why it’s a bad idea to embed usage info or instructions about the contents or meaning of a parameter file into that very file.

If you don't embed those comments you bereft that file of context -- why, as you admitted "is everything".

>Somewhere else, something has to choose to load that file, and that is where the documentation belongs (in addition to readable, separate artifacts that are generated from the file).

Well, that's not really relevant. People who change configuration are 99% of the time not the same as those who write/read/or even have access to the code that reads it.

Imagine Apache or Postgresql configuration for example.

Admins change those all the time, but don't have anything to do with the Apache or Postgresql project, and don't ever care to read their code.

On top of that, my particular settings in some config file, are based on MY local server and needs and my context, and not on something Postgresql or Apache devs will know themselves.

System admins who might change e.g. Postgres config files absolutely should be proficient in looking at documentation or the source code to understand the meaning, and then create separate documentation about their own customized config files (not making others or their future self actually have to read that file to understand why a value was chosen).

But more generally, it’s bad that a lot of applications don’t offer documented ways to modify config through ENV variables.

A config file should always be code reviewed, versioned and checked into SCM. One side effect is that end users, sys admins, etc., should never be given the chance to inject their customizations through locally modifying the base config file. That should be straight disallowed, so that distributing config files (such as the default, or bundles of other settings commonly used in unison) is part of packaging and deployment, and end users use other mechanisms that allow overriding defaults in a case by case manner.

Then you are talking about perhaps a shell script that sets dozens of ENV vars to override what comes from a (never modifiable) config file, and sure you might document the why of your choices in that shell script with comments, and at no point would anyone need or want comments in the actual config file(s).

Suggesting that most developers who use postgres should be familiar with its source code is madness.

Expand this to everything a sysadmin has to manage it just doesn't scale.

> “Suggesting that most developers who use postgres should be familiar with its source code is madness.”

This is a glib strawman that has nothing to do with what I said at all.

If you intend to modify config files directly, then you should be able to find the relevant documentation, source code comments, etc., on what the config entries mean or why a value is chosen as the default without needing comments in the config file. This is in no way related to your wild idea that “most developers who use postgres should be familiar with its source code..” (which is not at all what I said and is not at all a reasonable characterization. Reading a tiny bit of source code or docs to find one type of comments is utterly and completely different than your gross mischaracterization that it’s somehow a claim that people would need to be deeply familiar with a bunch of source code.)

> I actually appreciate JSON omitting these features.

I guess this is right if config files are only machine read and written. When I am prototyping, config auto-gen tends to come pretty late in the project (for me), and I like being able to comment things.

I also like types and time-date parameters (which JSON doesn't provide unambiguously), so by the time I've done, I've reinvented YAML+, and that's a mess, so I actually appreciate TOML quite a bit... (At the very least - I get to be a retard[0] about config later in the process)

[0] To the inevitable person that's going to call me an able-ist for using the term, I'm using the term in a self-denigrating way, ...

> "I guess this is right if config files are only machine read and written."

No, I meant omitting these features is very useful for humans reading and writing config files. Comments utterly don't belong in config files. They belong in the sections of code that load specific config files and convert their contents into defaults or parameters.

A config file is just some file. Its contents have no conventional meaning. It only takes on a meaning in the context of the specific system that uses it.

Hugely disagree. Config files will modified by non-experts of the application 1000x as often as the actual developer of the application. Those people won't and often can't go look at the code.

Also, it can be really hard to find where exactly a configuration value is used. You may have to trace through a ton of code to find the place, and then you can't be sure that's the only place it's used.

Configuration comments are crucial, both for onboarding new users (explaining what the default is if you don't set a value, explaining what the configuration value actually controls, etc) and for experienced users to tell others why this esoteric configuration is set the way it is.

A configuration file is literally just a stack of magic numbers and strings. Why are we setting threadpool to 10 and not 1000? Why are we disabling X feature? What the heck does TPS_Report=true do?

You need comments.

I disagree strongly. Config files being modified by anyone should be going through code review. The risk of not understanding while at the same time modifying things is extremely low.

Plus, the documentation in the application code that loads the config and manipulates would function as the exact same reference documentation for any developer trying to understand how the config is used or why a choice is made.

This prevents the documentation about what the config is supposed to be used for from being coupled with the implementation detail of what particular config file looks like, what language it’s written in, etc.

Just as you say, a config file is a stack of magic constants. They have no meaning at all sitting in that file. The place to look for their meaning is the documentation of the code that loads the file, which should tell the user everything they need to know about modifying or providing their own file.

IF you have a 500k LOC software project... how the heck is an SRE/devops person going to figure out where in that code a specific configuration item is going to be used? They're not. This is why documentation is essential for projects. You could keep configuration documentation in a separate file... but that only helps for what the config does. It can't help you figure out why Bill (who left the company a while back) set ThreadMax to 650 when he changed the code 6 months ago. There cold be a commit message that references it, but that's more disconnected from the change that just slapping a comment on top that says why.

I agree that code review for configuration changes is necessary. That same code review process can ensure that the comments in the config file are also correct.

> It can't help you figure out why Bill (who left the company a while back) set ThreadMax to 650 when he changed the code 6 months ago. There cold be a commit message that references it, but that's more disconnected from the change that just slapping a comment on top that says why.

Also worth noting is that not all config files are committed to version control as-is. If a deployment process bakes the config file from variables, it can be even more disconnected and difficult to find the change.

The size of the project is a red herring in your comment. People document command line options, ENV settings, etc., in huge projects all the time. It has absolutely no bearing on whether comments belong inside of config files.

> Config files being modified by anyone should be going through code review.

Yeah, I'll put in a PR for my local Transmission config file and see how far that gets me ;)

Config files should be understandable and readable by the end users so they can customize their local installs.

This is silly. If an app like Transmission expects end users to modify a config file locally as the means to add customized settings, that’s a seriously bad design. Why not provide documentation about command-line arguments or ENV variables it would look for for end user customizeability. A settings file where you need to know the meaning as you read the file is among the worst ways to solve it.

That might be correct. I tend to want to localize explanation at the edge. I've got to think about this. Thank you.

>They belong in the sections of code that load specific config files and convert their contents into defaults or parameters.

And what are users who don't have access to the source, or who aren't programmers, supposed to do?

Somehow these people are reading Toml files of config? That’s silly.

Do you expect a systems administrator to be familiar with the source of every software he maintains?

No, I expect the system administrator to refer to a readme, user guide or API doc that explains how to inject custom options at the command line or through a web API, etc., and absolutely never by mutating a config file outside of version control with code review from the team that maintains that specific type of config.

Take Apache or Postfix, for example, which are configured via possibly complex configuration files and not a “web API”. It is definely useful to have comments explaining configurations. For example, “here we deviated from the default for such and such reasons”. That’s true whether the file isn’t maintained manually or via some Puppet or Chef template or something else.

But if the config file has a comment like “here we deviated from the default...” it suffers the sane risk of being out if sync as the documentation would suffer anywhere.

So then, instead of forcing someone else to dig around a file like that, why would you put the docs about your modified config file somewhere else, and in a format that’s much easier to read?

For example you could make a whole git repository solely to hold a certain config file, allowing it to be versioned and even including an “install” script so that some other tool like docker could be used to faithfully reproduce a config setup.

Basically the only examples I have seen anywhere in this thread where people think in-line config comments matter are large desktop applications like Transmission or Postgres which have the unfortunately bad practice of letting users modify complex config files (instead of forcing all overrides of defaults to be ENV variable based).

And even in these cases, it seems more like lazy people who just personally prefer to sling a config file around rather than doing some minimal best practice like putting it in a repo to wrap it up like a mini-package and give much better documentation to someone who might “install” that config than what crappy in-line comments can give, and to enforce code review even for your own local config changes.

If you think there’s a risk of comments becoming outdated in a config file, then the risk of it becoming outdated in a separate place seems even higher.

Configuration via environment variables is as far from best practice as I can imagine. It prevents proper validation of settings (e.g. a typo can’t be detected because you don’t know which environment variables are used by other programs), not to mention the possible security implications. Besides, these environment variables would have to be set somewhere, like a startup shell script, which I bet would end up with explanatory comments anyway.

This trend of using environment variables is a result of trying to make applications stateless, therefore easier to run in containers. However with something like K8s ConfigMaps, it seems totally unnecessary.

> “then the risk of it becoming outdated in a separate place seems even higher.”

I’d say they are almost identical risks, and for all practical purposes there is no difference. Putting comments inside the config file only makes discovery much harder than putting it in a user guide, man page, etc. with no offsetting benefit of consistency.

> “Configuration via environment variables is as far from best practice as I can imagine”

You are arguing against perhaps the most dominant notion of config best practices in the modern era when you say that [0]. Quoting from the 12 Factor App best practices on config:

> “Another approach to config is the use of config files which are not checked into revision control, such as config/database.yml in Rails. This is a huge improvement over using constants which are checked into the code repo, but still has weaknesses: it’s easy to mistakenly check in a config file to the repo; there is a tendency for config files to be scattered about in different places and different formats, making it hard to see and manage all the config in one place. Further, these formats tend to be language- or framework-specific.

The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code; unlike config files, there is little chance of them being checked into the code repo accidentally; and unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard.”

You say,

> “This trend of using environment variables is a result of trying to make applications stateless, therefore easier to run in containers. However with something like K8s ConfigMaps, it seems totally unnecessary.”

I don’t think those are the reasons for putting config into the environment at all. I think a main reason is specifically so that end users modify config with ENV vars that disallow scattered and non-reproducible collections of config (e.g. if you share the command or script that defined the environment, the settings are enforced; if you share something that relied on a local config file you had modified but no one else knows about, they can’t get your settings).

[0]: < https://12factor.net/config >

> You are arguing against perhaps the most dominant notion of config best practices in the modern era

I don’t know that it’s “dominant”, nor that it’s good merely because it’s “from the modern era”. But even if all that is true, 12 factor apps constitute a small subset of configurable software that is deployed worldwide, and hardly a silver bullet for all kinds of software (it even defines itself as a methodology specific to SaaS applications).

Non-open source software.

Ops teams deploying a service.

Programmers who don't know the language a program is written in.

Heck what about a config file for a game? If setting the resolution it'd be nice if valid values are shown in the comments.

The argument is about comments in JSON btw.

Why would these people be modifying config files outside of code review? That’s horrible if true, and would entirely go against most best practices (e.g. 12 Factor use of ENV vars).

If you want to provide config customizeability as part of an API or interface to third party users (and you should!) then doing it by comments in a file that users modify is insanely bad. Instead, document usage instructions for overriding defaults with ENV vars — customization should never involve mangling a config file outside of version control, and absolutely not by third party devs, system administrators, etc.

In fact, I think your response highlights exactly why relying on comments in config files is such a bad anti-pattern.

> Why would these people be modifying config files outside of code review?

My VSCode config files are stored as JSON. They are hand modified all the time.

package.json is a user editable config file, used by millions of JS developers every day.

The .babelrc file to configure the JS transpiler is a user configurable json file.

.eslincrc, used to configure one of the world's most popular JS linters, user editable json file.

Those are all the ones sitting in one folder, and they would all be vastly improved with comments.

Especially the package.json, entire scripts live within package.json files, you run them with the command

    npm run <scriptname>

Right now there is no way to comment what the heck each script does! Sorta a PITA to have to go through each script, which can link to other scripts, to figure out what is going on when a simple comment would save a lot of time.

> customization should never involve mangling a config file outside of version control, and absolutely not by third party devs, system administrators, etc.

Config files in general? Of course they need comments.

What about users wanting to set custom key bindings in computer games?

Back in the day, customizing Quake settings was huge. All user editable config files. Little Jimmy's DOS 6.0 games folder wasn't using version control.

Even more recently, users modify config files, often times to fix or get around bugs in a games UI.

How about setting up a mail server? Those are all user editable config files. People running a local mail server aren't going through code review or version control. A sendmail config without comments would be even more impossible to read!

Or just simply .bashrc files.

Config files are used all over the place. Being able to document what happened is incredibly valuable. Not every file in the world needs version control.

> Instead, document usage instructions for overriding defaults with ENV vars

Environment variables are set through configuration files! That is just kicking the ball down the road.

You begin your comment with a big list of extremely bad designs for config management. The least important flaw of those examples would be any limitation on comments in the config file — they have severe problems well beyond that. Papering over problems in e.g. badly misused package.json files won’t solve anything, and because it would run the same risk of those comments getting out of sync with the entries of the file as any other way of documenting it, it could even be harmful.

The rest of your examples just rehash the same fallacy mentioned in other comments (which I’ve given adequate responses to already). Large apps that use a local config file are no exception to what I’m saying. That’s still a terrible way to expose customization to an end user, and even if you are modifying some big local config file, like with Postgres, you should be putting your config file into a separate version control repo, versioning it, having comments as part of that repo, treat it like a mini package that gets deployed or installed when you make any changes (which should be code reviewed always, even if you’re just talking about your own config file for some app on your home PC).

Environment variables should not be set through config files, that’s terrible. Rather environment variables being set explicitly should be the way you override whatever default would have been chosen from the config file.

> Environment variables should not be set through config files, that’s terrible. Rather environment variables being set explicitly should be the way you override whatever default would have been chosen from the config file.

How else do you propose environment variables be set?

Some script someplace has to set those environment variables.

A script that configures environment variables is awfully similar to a fancy config file. Indeed, in the interest of keeping code clean and organized, if a lot of constants, in the form of environment variables, are being set by a script, it might be a good idea to put them all in one file and just import that.

At which point you now have an actual config file!

> That’s still a terrible way to expose customization to an end user,

How would you do bashrc?

There are a lot of small problems for which config files a perfectly fine. Especially configurations aimed at technical users.

Creating a UI around configuration means developer time and effort, and that UI has the potential to have bugs. That UI needs to document what each configuration setting does, and what all the possible valid values are.

If all the config is trivial, and stored in a plain text file, then a text editor is perfectly valid UI for advanced users, and comments in that file serve the same purpose as documentation.

Hell you could make a transformer that takes a config file with documentation and pops out a UI. At which point you've unnecessarily complicated the UI of a text editor.

Indeed one of the niceties of VSCode versus Visual Studio is that VSCode has all its configurations stored in an editable text file. In Visual Studio settings were hidden behind a horrible UI that recently got search put in place. Until that happened, the common way to find a setting in VS was to look up on google where the setting was.

On a related note, Visual Studio uses what is called MSBuild files, fancy XML files that configure the build settings, and instructions, dependencies, etc, for a project. There is a nice UI around it. The nice UI likes to corrupt the configuration file. Advanced users quickly learn that modifying the file by hand is far superior.

> (which should be code reviewed always, even if you’re just talking about your own config file for some app on your home PC).

Bullshit! I am not creating a repro for my config file for my linter. I do however want this comment:

    // imports React Native builtin functions

in my linter config, which I'll set, and not ever change until I start a new project, copy and paste my linter config file, open it up, see that comment, and know if I need to keep that line or not.

Also comments in repros suck.

Repro comments do not comment on specific lines in a file, they are on the entire check-in.

External tools are needed to determine what commit modified a given line in a file. Hopefully that last commit has a comment about not just what that change to that line did, but what that line is for in general. Heaven forbid if multiple lines were changed.

If I am in the middle of editing a config file, I now need to task switch to another tool, potentially play "guess the commit", and piece together what that line in the config file actually does.

If I'm running some multi-million dollar system off of that config, sure, it can be worth it. But there is a HUGE productivity loss there in comparison to

    // boolean, false leaves tabs alone, true converts spaces to tabs

in a config file for my text editor!

Your entire viewpoint seems to be around mission critical software, which is great for mission critical software. But requiring git be installed so users can setup tabs vs. spaces is insane.

> "A script that configures environment variables is awfully similar to a fancy config file. Indeed, in the interest of keeping code clean and organized, if a lot of constants, in the form of environment variables, are being set by a script, it might be a good idea to put them all in one file and just import that.

At which point you now have an actual config file!"

I think this is specifically not what is recommended, e.g. read through [0].

> "How would you do bashrc?"

.bashrc is source code that gets executed, not config. Similar with .emacs, etc. Personally, I keep all of these things in a single git repo and then the local files are symlinked to the version controlled files, so that I can document any parameter changes through a PR in GitHub, and it's easy to distribute config files to new places (just clone these types of configs from git). A nice bonus is that putting comments into the config directly is not needed. Anyone (whether my future self or a friend who wants to use my configs from GitHub, etc.) can look at the readme / user guide for the git repo, and not need to go on a fishing expedition for ad hoc comments in the actual files.

> "Especially configurations aimed at technical users."

You can't have it both ways. If users are technical, then they can find what they need in readmes, user guides, and source code comments. There would be no benefit for the comments to be directly in the file, while having comments scattered all over and possibly out of sync from the intended usage instructions would be a downside.

On the other hand, if the user is not technical enough to modify settings in that way, then a user guide and some type of additional API for customization is needed. Overall this suggests the comments belong at the user guide / readme level, since that would be a beneficial way of working for both groups.

> "Bullshit! I am not creating a repro for my config file for my linter. I do however want this comment:"

This just seems like you use bad practices. I have a pretty heavily customized pylint setup for linting my code, and I absolutely do check it in. I actually wrapped it in a simple setuptools package so that I can say, "pip install <my private github URL>" and actually install my custom linting tools (and their settings) as a full (versioned) Python package complete with an exported shell script to control it. Then I can, for instance, just have a conda environment like "my-linter" that has absolutely nothing except for my installed linting tools, and make a bash alias that will source that environment, run the linter, and then deactivate. I'm even considering putting it all inside a Docker container instead of a Python environment.

> "Repro comments do not comment on specific lines in a file, they are on the entire check-in."

Maybe you are using different tools, but this is not true in any source control tool I have ever used. Certainly not true in GitHub or Gitlab.

I honestly don't know what you're talking about with the whole "guess the commit" stuff. Just navigate to a file in GitHub and look at the history (or do this from the command line once you feel comfortable reading file history). If looking at a file in GitHub is too much work for you, well, I can't help you. That's just not reasonable and speaks to extremely bad coding practices if inline comments in config are being used to circumvent meaningful code review that leaves useful commit history.

> "Your entire viewpoint seems to be around mission critical software, which is great for mission critical software. But requiring git be installed so users can setup tabs vs. spaces is insane."

This baffles me. I am not even sure I can parse this as a coherent comment. Requiring git to be installed? What? If you change a file from tabs to spaces, hopefully some linter complains at you based on whatever your team's conventions are. But if you mean changing a setting in a settings file somewhere, then yes, it ought to be checked into something. Why would you think it's reasonable to just hand-edit config like this with zero version history? That's just not reasonable.

To be clear, I am not talking about mission critical software for any of this. I am talking about any type of config you manage. I do all this just on my local machine for my Jupyter config, linting config, emacs, bashrc, etc., all just for my local laptop that I use for recreational programming and random personal computing. Obviously, it matters even more for commercial software.

[0]: < https://12factor.net/config >

Commenting on individual lines is a github extension, not something that the majority of source control software can do. (I've actually never seen any other source control software that can do that, but I imagine it exists somewhere).

Heck Github desktop doesn't even support it, I'd have to check in the file, go to the website, then add a comment. My linter files get thrown in the repro as a matter of fact, so they are at least checked in, but the other two things are more work than I want to worry about for some throw away file that I don't care about.

As to commit histories, I've spend hours of my life digging through commit comments (in multiple different source control systems) trying to find out what the hell some setting did. Often times the config file ended up being grabbed from a branch in some other project, and the revision history is gone.

I've also spent probably dozens of hours of my life tracking down what some random environment variable does. Joy.

Realize you are an extreme outlier. The majority of people in the world do not commit every single config file for their personal projects, nor do they use commit messages as a way to track individual settings changed in the file.

> Why would you think it's reasonable to just hand-edit config like this with zero version history? That's just not reasonable.

Because that is what the majority of people on the earth do. Because it works just fine. Because I have a thousand things to worry about trying to run a startup and the commit history of some file that I really don't care about isn't that important. Being able to write a comment is a nice to have so if by some odd chance I come back to the file years later I know what the heck I did.

I think it is reasonable because life is full of trade offs, and limitations on time, and not everything can be perfect.

> .bashrc is source code that gets executed, not config. Similar with .emacs, etc. Personally, I keep all of these things in a single git repo and then the local files are symlinked to the version controlled files, so that I can document any parameter changes through a PR in GitHub, and it's easy to distribute config files to new places (just clone these types of configs from git). A nice bonus is that putting comments into the config directly is not needed. Anyone (whether my future self or a friend who wants to use my configs from GitHub, etc.) can look at the readme / user guide for the git repo, and not need to go on a fishing expedition for ad hoc comments in the actual files.

I agree github is useful to distribute files, easy to checkout from. But the bashrc on my server is one I copied and pasted by hand, because that is Good Enough(tm) for use on a machine that I'll use the shell for maybe a grand total of 30 minutes a year. Setting up git and going through two factor auth for a file that is literally Never Ever Going To Be Changed serves no purpose. The world would not be better place because a bashrc on a VM is under source control.

Also I'd then have an external facing server with a copy of a personal repro laying around, which could be an information disclosure problem if someone breaks into the server and I check something into github that I shouldn't. (Even non-obvious stuff, like machine names or paths used on internal machines is a type of information disclosure that increases risk.)

(really my VPS provider just had a crap default config that didn't show the current working directory at all, so the bashrc there is a single line)

Likewise, with most of my config files, they are throw away, or write once edit rarely.

FWIW it sounds like you are using github comments instead of inline comments. This only matters if you care about why a line change was made. If you just want to know what a line does, then using comments on github provides no more functionality than adding a comment to the file, except looking up comments on github takes longer.

Checking config files into repros to easily spread them among projects makes sense if you have enough overlap. But saying that github line comments are the one true way to comment lines in a config files is making an absolute statement that you know what is best for everyone's situation. Such a scheme adds no extra value if someone just wants to know what a given line does right now. And I can't think of ever having wanted to look at the history of my linter config. If I am copying it over to a new project, I want to know what lines to keep and what lines to delete based on the type of project I'm doing. Comments in the config file would allow that. Except I don't have comments because JSON doesn't have comments.

In which case I'm now thinking of github line comments as an ugly hack around JSON not having comments.

You make some interesting assertions, but 1) they contradict everything I have learned from painful experience and 2) they seem to make no sense.

> 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

Okay, I'll bite: Why? In every area of programming, we learn that mental context changes are harmful. We learn to avoid gotos, not abuse exceptions, add meaningful comments, and seperate concerns all in large part so when we look at a file, we can understand what's going on without referencing other files.

Now you say "oh, unless there are some config values in that file, then it's important for it to be as cryptic as possible!" Surely you see why that sounds a bit odd? Should we also base64 encode the file? Do you also hate descriptive variable names in config files?

>Config files should absolutely not have or need comments.

Well, that's like your opinion, man.

If I have something set to some value in my configuration, I want those reading the configuration file (not parsing it, reading it in a text editor, e.g. to make an edit) to know why it's so.

>Applications should document their default settings in a different way

Comments in configuration files are not there to explain default settings, but to document why a setting (default or not, but usually already edit to suit your specific environment) has the value you set it to.

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

That's a statement, not an argument. Why does it "belong elsewhere"? So that you have an extra layer, that few will bother to check?

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.

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

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

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

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.

There's the JSON5 format that supports comments, there are libraries available for parsing and encoding it.

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

So now your comments are flowing through infrastructure wasting bandwidth and possibly leaking internal configuration details?

And maybe even breaking code which doesn't what to do with these fields.

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.

Hey Tom,

I just wanted to say thank you real quick.

We use TOML in [Habitat](https://github.com/habitat-sh/habitat) to define default and overridable configuration. It's super easy and expressive.

The [Habitat Core Plans](https://github.com/habitat-sh/core-plans) have quite a few examples about how it gets used in the project. If you are looking for examples of larger configuration files with .toml, then that might be a good place to look for some real world use.

Thank you again!

Amazing, thanks for the heads up! I'll add it to the list of projects using TOML [1] and take a look at your example configs to get some more real-world uses cases to look at when evaluating future changes to the spec.

[1] https://github.com/toml-lang/toml/wiki

Quick link to a complex one:

https://github.com/habitat-sh/habitat/blob/master/components...

I'm a pretty big fan of TOML, though I've mostly only used it for Cargo.

What are the limitations for large complex configs, and do you think there's currently a better configuration format for them? Feel free to link elsewhere if there's a canonical location for this discussion.

The limitations are mainly around nested arrays of tables. As has been mentioned here already, the [[array-of-tables]] syntax that currently allows this can be super confusing, and is definitely the worst part of TOML right now. Even so, you can often work around this weakness by reworking your config file to pick up on a specific naming scheme (perhaps every "server-*" table is interpreted as a member of an array) or maybe there's an array of strings that contains the names of the tables, each of which becomes an array member in that order. But these are hacks, and it would be nice to have a first-class way of dealing with nested large tables that was easy to scan and not too repetitive.

That said, the alternative right now in other formats is basically a { bunch { of { braces } } which is also not the most amazing thing for long nested tables.

Thanks, is there a strawman proposal out there for fixing this, or is it something for the distant future?

> The limitations are mainly around nested arrays of tables. As has been mentioned here already, the [[array-of-tables]] syntax that currently allows this can be super confusing, and is definitely the worst part of TOML right now.

Good to know this is recognized. Looking forward to a better syntax to an indeed difficult problem

is this e.g. due to the verbosity of re-declaring field names every time? or something else?

e.g. CSVs handle 2D tables reasonably efficiently, since you just specify values:

    field_a, field_b, field_c
    1, 2, 3
    3, 4, 5

but I imagine TOML would benefit from something that lets you define nested tables without re-defining the table every time... which probably conflicts with the "obvious" goal. Hmm.

I think HCL (Hashicorp Configuration Language) reads much better than TOML when there are nested sections in the config file.

Hi Tom, huge fan of this project.

1. Would a file path type make any sense to add? TOML is ideal for configurations, and so many configuration options use file paths. I know there are questions about platform dependency, and I don't have all the right answers for how that would work, but I could see it being possible somehow?

2. Data versioning is a big deal to me. For now there's always an option of just adding a "version" key and updating it, but can you think of a better way to do that with TOML?

I'm always overly critical of JSON (despite overall being a fan) because it doesn't specify bit sizes of numbers. I notice that TOML has specified 64 bit numbers. It's nice to see that.

1. How would the file path type differ from a regular string? Would you want specific semantic validation for each platform?

2. This is still a big question, and we've been having a robust argument about it on GitHub [1]. It's a problem that so far has evaded an elegant solution, but usually when that's the case, it just means we haven't been creative enough about it yet! Or did you mean versioning of the data IN the config file? Can you elaborate?

[1] https://github.com/toml-lang/toml/issues/522

1. Yea the goal would be some kind of validation at parsing time. I'm not super familiar with TOML parsing, but there must be error cases in the implementations, so it seems like using `\` on UNIX systems, for example could return an error. The only hard part about this I see is distinguishing paths from strings syntactically without making TOML overly complex.

2. So basically, the majority of people don't want to type version numbers (I see where they are coming from, but respectfully disagree). I'm not sure if there exists a solution in that case. As for my comment, I was really talking about both kinds of versioning. Mainly that, if my data is version 2.3.1, I'd expect that to also lock the version of TOML, requiring a new version of my data for bumps to the underlying data structure. Again syntax is the hard part, as I'm having trouble imagining a way to actually do this. Furthermore I've seen data formats in the past that let you version "parts" of a format, I personally like this, but don't think it's a good fit for TOML.

Backslashes are valid characters in a POSIX filesystem, but they don't indicate a directory.

Yeah...rather than validating paths, the better use case is probably normalizing them so that you don't need platform-specific configuration files. Being able to write:

static-files = path/to/static/files

And have it work on all platforms gives a distinct advantage over specifying paths as strings.

That was my first thought, but imo such a functionality belongs in the language's file access library.

Every modern operating system accepts forward slash paths. It's been a long time since there was any need for things like Python's os.path.join() or special file path knowledge in config files to convert slashes to backlashes on Windows. You can just use forward slashes everywhere and not worry about it.

The one exception on Windows may be paths in a CMD.EXE command line, where / may be confused for a switch character, but I would think a config file should not be passing paths on a command line but instead passing them directly into a program - and then the forward slash will work fine.

Tom, have you heard of EDN and Transit? Like JSON, but:

1. Extensible, custom types

2. Streamy, efficient, compressed and fast, leverages platform's existing native/optimized JSON parsers

3. Wide platform reach

4. Made by Rich Hickey

http://blog.cognitect.com/blog/2014/7/22/transit

I have not, and while it looks cool, it seems to be optimized for data transfer between applications, not a human readable config format.

Transit is more about data transfer, but EDN is mostly meant to be a better JSON (useful date types, doesn't care about commas, has comments, etc)

There is also a similar project - Hjson, a user interface for JSON- https://hjson.org/

For me, hjson takes on some of the warts of yaml (bare strings) which is why I prefer json5 if I'm going for a json variant.

That TOML started out tongue-in-cheek makes it all that much better!

Just a curious thought:

Sometimes it’s handy to have a text file for small bits of numerical data. Would it be possible to extend TOML to have a “csv” section (array of arrays)?

    [x,y,z]
    1,2,3
    4,5,6
    7,8,9

Or perhaps it’d have to be:

    [data: x,y,z]
    1,2,3
    4,5,6
    7,8,9

Tom here (not the creator or TOML). Every time I have a "what are we using for configuration" discussion at work for a new project, I get to say "let's use TOML, it's obviously superior, just look at it's name!".

It's a horrible joke and I've yet to actually use it, but it makes me happy :)

> There are still some weaknesses in TOML that make it non-optimal for large, complex config

May be the config shouldn't be large and complex in the first place?

My biggest question is, why hasn't TOML used much more widely or becoming de facto standard? Am I missing something obvious?

I'm always in favor of small config files, but sometimes for larger projects that's just not possible (or desirable). TOML has always been about being as simple as possible while still solving a wide range of problems. But I think of it as the 80% solution, where 20% of projects might need something more powerful to solve their more complex needs, and that's ok. We still need a super simple config file format for the 80%.

As for adoption, it takes a long time for something like TOML to be adopted. Inertia is powerful in the development space. I also haven't had as much time as I would like to push TOML forward and evangelize it. My hope is that at some point there will be a tipping point and you'll see most projects start with a TOML config and only change to something else when TOML can't meet the project's needs.

Yes I've got a project and config that I tried to stuff into TOML and even make my own DSL for it, but I haven't gotten anything satisfactory still. I've settled on some semiugly yaml for now until I try again

https://github.com/perlbot/App-EvalServerAdvanced/blob/maste...

The rest of the sandbox is configured with TOML however. Just seccomp rules that I haven't figured out the perfect way yet.

The one problem I've had, and perhaps I'm just doing something incorrectly, is going from a `[[something]]` back to a `[thing]` without TOML thinking that `thing` is part of `something` it's not.

Curious. In order to be part of one of the tables in the [[something]] array, a table would need to be named [something.X]. What parser are you using? it's possible that it's behaving improperly in this case.

See the relevant part of the spec here: https://github.com/toml-lang/toml#user-content-array-of-tabl...

Hi Tom. Dave here. I like a lot of the features in TOML, but I'm curious, can I have a pony?

(Folks downvoting, PLEASE JUST LET PEOPLE HAVE JOKES EVERY NOW AND THEN)

Hi Dave! Ponies come standard in TOML, you just have to know where to look. =)

No soup for you.

Toml is better than a pony. Proof: http://toml.versus.horse

You aren't going to change what people around here like. And complaining about downvotes usually just attracts more.

If you think that your brand of funny is worth braving people's disapproval, do it knowing what the reaction is going to be. If you don't like people disapproving, then go elsewhere, or engage here in a way that people prefer.

I made the joke for Tom. It has special significance for him.

Dave and I worked together at Powerset many years ago (pre-GitHub) and wrote a bunch of Erlang together. We have a lot of inside jokes from those days. LEAVE HIM ALOOOOOOOOOOOONE!

That's fine then. Make the joke for Tom. Ignore the inevitable downvotes. Nobody else has to understand or like it.

This project reminds me of the good old INI files.

As it should! It was inspired by INI, but with a desire for a proper spec that unambiguously maps the config file to a hash table.

This was the first thing I noticed as well. It was always somewhat alienating when encountering newer formats that were less friendly than what came before. I think TOML does a good job of taking what came before and bringing it forward.

Over the many years of the usage of INI I think occasionally we've seen developers add their own touches to how they support types, sections, groups, multi-dimensional arrays or other structures within config files that certainly indicated a need for some more standardized advancement here.

I really hope this gains a lot of traction, because there are so many scenarios where things like XML or JSON are forced into roles they really don't belong in.

One thing that I would say is that it might be worth indicating a standard header that can be used at the very least in cases when it is not stored in a file with a .toml extension. It would not surprise me at all to see TOML widely used with extensions that describe better the intent of the file rather than the format.

damn it.. of course you would update the spec right before I release my config parser. =)

I have been working on a TOML reader/writer for golang that supports read/change/write and format (like go fmt) that sometime I will get enough time to actually finish and release. =)

Hah, sorry! You can always release an 0.4 compatible first, and then add the stuff from 0.5. Sounds like a great project!

TOML needs anchors (like yaml)

So like YAML, TOML ain't markup language either, despite the recursive acronym and the "ML" suffix. If your name was Mark instead of Tom, would you have named it MARKML, and would it still not be markup language?

This does not claim to be a markup language.

According to the repo history, it did... 5 years ago, until someone noticed and corrected it.

Reply on news.ycombinator.com