OP's argument is silly. JSON files are fine for config.
OP's argument is silly. JSON files are fine for config.
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.
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.
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.
# 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.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
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.
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.
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.
He does explain, there is even an example.
How about putting instructions in the instruction file (README) and configuration data in the config file?
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.