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

181–190 of 204 posts

Re: Toml: Tom's Obvious, Minimal Language

#181

Post by mlthoughts2018 »

com2kid wrote: post #152
mlthoughts2018 wrote: post #140

Earlier quoted context omitted.

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

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.

Re: Toml: Tom's Obvious, Minimal Language

#182

Post by mlthoughts2018 »

andrenth wrote: post #148
mlthoughts2018 wrote: post #140

Earlier quoted context omitted.

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.

Re: Toml: Tom's Obvious, Minimal Language

#183

Post by erikpukinskis »

tpaschalis wrote: post #62

Just dropping a useless comment to say thanks! Between Tom's work on Github, Jekyll, and TOML, I think he has influenced a vast amount of developers! For the projects I've used TOML on, it was a nice breath of fresh air and a terrific improvement over JSON (still mad about JSON's lack of comments). Simplicity wins!

Not to mention inventing MySpace!

Re: Toml: Tom's Obvious, Minimal Language

#184

Post by mlthoughts2018 »

UncleEntity wrote: post #146
mlthoughts2018 wrote: post #138

Earlier quoted context omitted.

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.

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.

Re: Toml: Tom's Obvious, Minimal Language

#185

Post by [deleted] »

Pxtl wrote: post #86
mojombo wrote: post #46

Earlier quoted context omitted.

Absolutely. That's what I mean about TOML mapping unambiguously to a hash table. Strings in TOML are always quoted. There is no fuzzy interpretation of things like YES and NO. That way madness lies. I also am not a fan of meaningful whitespace, which is why TOML doesn't do that. Glad you're finding TOML useful, good luck on your projects!

> There is no fuzzy interpretation of things like YES and NO I think the big problem is that YAML is dynamically typed. If I had schema-enforced config files, I'd be perfectly happy to say that for boolean typed data all the values of YES and NO and ON and OFF and T and F and 0 and 1 can all be reasonably interpreted as a Boolean True and False. The problem happens when a string-typed or integer-typed member can also…

[deleted]

Re: Toml: Tom's Obvious, Minimal Language

#186

Post by mlthoughts2018 »

coldtea wrote: post #176
mlthoughts2018 wrote: post #143

Earlier quoted context omitted.

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

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

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

Re: Toml: Tom's Obvious, Minimal Language

#187

Post by mlthoughts2018 »

natefinch wrote: post #141
mlthoughts2018 wrote: post #138

Earlier quoted context omitted.

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

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.

Re: Toml: Tom's Obvious, Minimal Language

#188

Post by andrenth »

mlthoughts2018 wrote: post #182
andrenth wrote: post #148

Earlier quoted context omitted.

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.

Re: Toml: Tom's Obvious, Minimal Language

#190

Post by com2kid »

mlthoughts2018 wrote: post #181
com2kid wrote: post #152

Earlier quoted context omitted.

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

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

Post reply on HN