4 ms·

> 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

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

ordinaryperson 8y ago
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.
- kbenson 8y ago
  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.
- spc476 8y ago
  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.

ordinaryperson 8y ago

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.

kbenson 8y ago
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.
spc476 8y ago
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.