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

[com2kid]

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

[mlthoughts2018]

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

[com2kid]

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.