[mlthoughts2018]

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

[natefinch]

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.

[mlthoughts2018]

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.

[natefinch]

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.

[DCoder]

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

[mlthoughts2018]

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.

[UncleEntity]

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

[mlthoughts2018]

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.

[com2kid]

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

[mlthoughts2018]

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

[andrenth]

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

[mlthoughts2018]

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.

[andrenth]

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.

[mlthoughts2018]

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.

[com2kid]

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.

[mlthoughts2018]

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.

[com2kid]

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

[mlthoughts2018]

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.

[ci5er]

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