Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Toml: Tom's Obvious, Minimal Language

github.com

Post reply on HN
Print view View original

141–150 of 204 posts

Re: Toml: Tom's Obvious, Minimal Language

#141

Post by natefinch »

mlthoughts2018 wrote: post #138
natefinch wrote: post #136

Earlier quoted context omitted.

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…

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 p…

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.

Re: Toml: Tom's Obvious, Minimal Language

#142

Post by elcritch »

mojombo wrote: post #10

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 la…

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

Re: Toml: Tom's Obvious, Minimal Language

#143

Post by mlthoughts2018 »

Waterluvian wrote: post #110
mlthoughts2018 wrote: post #109

Earlier quoted context omitted.

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 document…

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

Re: Toml: Tom's Obvious, Minimal Language

#144

Post by kvark »

timvisee wrote: post #68

Cool. TOML is used quite extensively in Rust projects. I think it's awesome for very simple configurations. And newcomers don't have to learn anything in order to change a TOML configuration, which is very powerfull.

TOML is a great format, but it can not universally replace JSON, because it's designed for small nested depth.

I've been trying to push RON as an alternative, and it works very well for WebRender, Amethyst, and other projects in Rust.

Re: Toml: Tom's Obvious, Minimal Language

#145

Post by zbruhnke »

dmurray wrote: post #123
Waterluvian wrote: post #110

Earlier quoted context omitted.

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

Re: Toml: Tom's Obvious, Minimal Language

#146

Post by UncleEntity »

mlthoughts2018 wrote: post #138
natefinch wrote: post #136

Earlier quoted context omitted.

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…

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 p…

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

Re: Toml: Tom's Obvious, Minimal Language

#147

Post by Lazare »

mlthoughts2018 wrote: post #109
gregn610 wrote: post #92

Earlier quoted context omitted.

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 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 document…

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?

Re: Toml: Tom's Obvious, Minimal Language

#148

Post by andrenth »

mlthoughts2018 wrote: post #140
com2kid wrote: post #139

Earlier quoted context omitted.

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

Re: Toml: Tom's Obvious, Minimal Language

#149

Post by andrenth »

hyperpape wrote: post #54
mojombo wrote: post #10

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 la…

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.

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

Re: Toml: Tom's Obvious, Minimal Language

#150

Post by Stratoscope »

curun1r wrote: post #89
bqe wrote: post #71

Earlier quoted context omitted.

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.

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.

Post reply on HN