Exactly. Also, OP does not explain the need for comments in a config file. I mean, do people consider Apache config files -- which extensively use comments -- to be a shining example of clarity? Hundreds of lines long, impossible to parse manually. Good luck finding those 3 lines you need.
OP's argument is silly. JSON files are fine for config.
> I mean, do people consider Apache config files -- which extensively use comments -- to be a shining example of clarity? Hundreds of lines long, impossible to parse manually.
You're conflating two things, the readability of very large config files, and the readability of config files that allow comments.
> Good luck finding those 3 lines you need.
Personally, since I live in a world where searching text in a file is commonplace and trivial, additional text to match, possibly even comments that note where the config differs from the stock one that ships, are useful.
The comments of these config files are part of what make them unreadable, these are not two unrelated issues.
Yes, searching Apache config is pretty much the only reasonable way of finding what you need. But have we really gotten to the point where we passively accept gargantuan, unreadable config files because it's possible to search for the exact pattern you need?
What if there's a problem in your config and you need to find the issue? Prepare to set aside a few hours of your time to read every block.
I just looked at some random configuration file on my system. Right at the top, in the comments was the following:
# Please don't edit this file directly (it is updated with every Red Hat
# Linux update, overwriting your changes). Instead, edit /etc/...
Nice. I now know to make changes in a file that won't be overwritten by an update, and if there are issues, it's either with the site local file, or the one provided by Red Hat, and it's probably (although not exclusively) the site local file that is in error.
Have you never piped a config file through grep to exclude comments to get a streamlined view? It's pretty easy, and quickly gives you the best of both worlds. Configure your editor of choice to collapse comments and that's an even more convenient interface.
For stock configs that ship with a lot of comments, I would sometimes replace the file with one where I've stripped the comments. Since I always save the stock config as $FILE.dist, I get maximum usability. Never would I want the configs to no support comments though. Even after I've stripped configs, I might add my own comment to each change from the stock config, or for some test change I'm trying out. Not having comments means any documentation would need to be at least one degree removed from the item it's documenting. Sometimes that's acceptable, sometimes it's not.
OP does not explain the need for comments in a config file
The same reasons you'd want comments anywhere else. As one example, often in a package.json file I want to add a comment that a dependency is intentionally using an older version due to an incompatibility. The workaround is to use a key of "//", which is hideous: https://github.com/npm/npm/issues/4482
Agreed that workaround are hideous, but no, it's not immediately obvious to me we need configuration data (which should be self-explanatory) glossed with comments.
Username? Got it. Password? OK. Hostname? Sure. Why do these things need comments?
If there's subtleties to the config, put that in the README. Or give better names to variables.
Functions are not always self-explanatory and get complicated fast, so comments in programming make a lot of sense and are helpful. A config file in theory should just be a series of assignment variables-- it's not clear to me why these require detailed explanations.
Comments in config are useful in the same way that comments in code are useful --- to point out things that are non-obvious to other people who work on the same config.
Things like listen on port 8081 instead of port 80, because the loadbalancer does something weird. Or this strange config is important because of feature X and blah. Or if you change this here, be sure to change it there.
To add to what 'toast0 wrote - code is about what; comments are about why. Even if your program has config so trivial that they're clearly data and not code, data alone doesn't tell you why it looks the way it looks. "username=admin" doesn't need explanation about what it was, but it might need an explanation if "admin" isn't what's typically expected as user name here, and is e.g. your specific workaround for something.
Apache conf files in practice suffer from people editing from the 'example' file to what they want and leaving all the embedded documentation.
When you build a file from scratch, or delete the embedded documentation as you go, you end up with reasonably compact configuration.
Additionally, apache has like thousands of options because it's software built to adapt to the world, and not software built for the world to adapt to it, so that adds to length.
No, he complains that comments are not possible and the example he references is about the workaround some people use but he accepts a priori the need for comments in a config file. Why do I need explainers in my config file?
How about putting instructions in the instruction file (README) and configuration data in the config file?
You can die from vitamin poisoning. Doesn't mean that vitamins are bad. Similarly, too many comments are obviously not a good idea, but that doesn't mean you never need them.
There are many cases you need an occasional comment: to explain why a possible surprising value is set to what it is, for example. Or to warn future editors for a mistake you made in the past, or even to just describe what a potentially confusing setting does.
Comments in most /etc files on Linux are fantastic - you can skim the config file and often find what you need, and you often know what is irrelevant, and the comments often warn you against common failures.
OP's argument is silly. JSON files are fine for config.