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 documentation that also explains how to use environment variables to override the defaults. That sort of separate companion doc is the right place for notes about defaults or "why" certain config values exist in the file. The same is true for using JSON to store parameter files, etc. 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, and it's an anti-pattern IMO to rely on comments in the config / param file.
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
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.
Maybe that makes sense for the app you are writing that is only consumed by others at your company, but if I'm installing your app from a package manager I absolutely do not want to have to read the config loading source code to figure out what all the parameters do. And even if the docs are nicely described in a man page and not in config file comments, I absolutely want to be able to comment on particular parameter changes ("# had to up foo to 18 because bar was frobbing baz at to high a rate").
Even if you use configuration management it's still nice to be able to comment things in config files since they show up both in the source and in the output files, which is very helpful when debugging.
I specifically meant that comments aren’t a good idea in config files when the config files are distributed to any end users as part of some app or package installation.
> “And even if the docs are nicely described in a man page and not in config file comments, I absolutely want to be able to comment on particular parameter changes ("# had to up foo to 18 because bar was frobbing baz at to high a rate").”
This is the exact anti-pattern that happens as a result of relying on comments in the config file. Your goal of adding that comment about why you changed foo directly in the config file is dangerous and is a very bad practice.
Instead, whatever config file it is that you are modifying (whether for third parties to consume or just for own local Postgres or video game or anything), that file should be turned into a proper package. Place it in a version control repo, and readme and usage documentation for the “why” of the parameter values, and make a tool so that if the end user wants that exact config file, they can “install” it.
For any customized overrides of single settings at run time (so specifically not changes to a config file), it should happen via the end user overriding ENV variables, not mucking around in config files and trusting ad hoc comments found inside them.
>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 artifacts that are generated from the file).
Well, that's not really relevant. People who change configuration are 99% of the time not the same as those who write/read/or even have access to the code that reads it.
Imagine Apache or Postgresql configuration for example.
Admins change those all the time, but don't have anything to do with the Apache or Postgresql project, and don't ever care to read their code.
On top of that, my particular settings in some config file, are based on MY local server and needs and my context, and not on something Postgresql or Apache devs will know themselves.
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).
> “Suggesting that most developers who use postgres should be familiar with its source code is madness.”
This is a glib strawman that has nothing to do with what I said at all.
If you intend to modify config files directly, then you should be able to find the relevant documentation, source code comments, etc., on what the config entries mean or why a value is chosen as the default without needing comments in the config file. This is in no way related to your wild idea that “most developers who use postgres should be familiar with its source code..” (which is not at all what I said and is not at all a reasonable characterization. Reading a tiny bit of source code or docs to find one type of comments is utterly and completely different than your gross mischaracterization that it’s somehow a claim that people would need to be deeply familiar with a bunch of source code.)
I very much disagreed with you two comments up, but this more fleshed out response actually makes a lot of sense. You just moved me from "I'm going to add a build rule that strips comments from all my JSON files so that I can have comments in my configs" to "The next time I want comments in JSON, I'm going to see if what mlthoughts2018 said makes sense in this case. Do I really need to comment this JSON file, or would it be better to put the comments somewhere else instead?"
You're talking about comments that document the semantics of fields in a config file. Most other people here are talking about comments that describe why the _specific values_ present in a _specific file_ were chosen.
Whether documenting semantics of fields belongs in a config file or code (I say both!), it simply doesn't make any sense to say that comments about why specific values in specific files are the way they are belong in the code that parses them. (How can the parsing code have knowledge of all config files out there?)
No, I am talking specifically about comments or documents that explain the "why" behind parameter choices. For canonical defaults that are shipped with an app, this should be documented in a user guide and in the appropriate parts of the source code, not inside the config file (which most users would never care to read, and which would be worse to read for most developers who might care or change it).
For local config files that are not shipped with the package, they should still be source controlled in a separate repo (yes, even if you personally are the only one using it, like your local Postgres configuration or something), and you should use a good practice to 'deploy' any changes to your config from the repo into the actual location where the application can recognize that config -- meaning that documentation about the "why" of the parameters once again should absolutely not be embedded inside the config file itself.
If they're not in the config file, where exactly are they then?
A text file sitting next to the config file? I can't see any benefit to that arrangement over just using comments in the file.
Comments that exist in the file in the repo but get stripped out by the deploy process? Again, there seems to be no point to doing this.
Commit log messages? I agree commit logs can sometimes be valuable to see the context of a change, but 1) they're fundamentally about documenting _changes_, not the contents themselves, and 2) the UI is really clunky: git blame, find the line you want context for, then git show on that commit.
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?
>Config files should absolutely not have or need comments.
Well, that's like your opinion, man.
If I have something set to some value in my configuration, I want those reading the configuration file (not parsing it, reading it in a text editor, e.g. to make an edit) to know why it's so.
>Applications should document their default settings in a different way
Comments in configuration files are not there to explain default settings, but to document why a setting (default or not, but usually already edit to suit your specific environment) has the value you set it to.
>Information about why a file contains those values belongs elsewhere, and it's an anti-pattern IMO to rely on comments in the config / param file.
That's a statement, not an argument. Why does it "belong elsewhere"? So that you have an extra layer, that few will bother to check?
> I actually appreciate JSON omitting these features.
I guess this is right if config files are only machine read and written. When I am prototyping, config auto-gen tends to come pretty late in the project (for me), and I like being able to comment things.
I also like types and time-date parameters (which JSON doesn't provide unambiguously), so by the time I've done, I've reinvented YAML+, and that's a mess, so I actually appreciate TOML quite a bit... (At the very least - I get to be a retard[0] about config later in the process)
[0] To the inevitable person that's going to call me an able-ist for using the term, I'm using the term in a self-denigrating way, ...
> "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.
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?
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.
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.
> 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.
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.
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.
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.
> “then the risk of it becoming outdated in a separate place seems even higher.”
I’d say they are almost identical risks, and for all practical purposes there is no difference. Putting comments inside the config file only makes discovery much harder than putting it in a user guide, man page, etc. with no offsetting benefit of consistency.
> “Configuration via environment variables is as far from best practice as I can imagine”
You are arguing against perhaps the most dominant notion of config best practices in the modern era when you say that [0]. Quoting from the 12 Factor App best practices on config:
> “Another approach to config is the use of config files which are not checked into revision control, such as config/database.yml in Rails. This is a huge improvement over using constants which are checked into the code repo, but still has weaknesses: it’s easy to mistakenly check in a config file to the repo; there is a tendency for config files to be scattered about in different places and different formats, making it hard to see and manage all the config in one place. Further, these formats tend to be language- or framework-specific.
The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code; unlike config files, there is little chance of them being checked into the code repo accidentally; and unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard.”
You say,
> “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.”
I don’t think those are the reasons for putting config into the environment at all. I think a main reason is specifically so that end users modify config with ENV vars that disallow scattered and non-reproducible collections of config (e.g. if you share the command or script that defined the environment, the settings are enforced; if you share something that relied on a local config file you had modified but no one else knows about, they can’t get your settings).
> You are arguing against perhaps the most dominant notion of config best practices in the modern era
I don’t know that it’s “dominant”, nor that it’s good merely because it’s “from the modern era”. But even if all that is true, 12 factor apps constitute a small subset of configurable software that is deployed worldwide, and hardly a silver bullet for all kinds of software (it even defines itself as a methodology specific to SaaS applications).
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.
> "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.
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.
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 documentation that also explains how to use environment variables to override the defaults. That sort of separate companion doc is the right place for notes about defaults or "why" certain config values exist in the file. The same is true for using JSON to store parameter files, etc. 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, and it's an anti-pattern IMO to rely on comments in the config / param file.