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