3 ms·

>They belong in the sections of code that load specific config files and convert their contents into defaults or parameters. And what are users who don't have

>They belong in the sections of code that load specific config files and convert their contents into defaults or parameters. And what are users who don't have access to the source, or who aren't programmers, supposed to do?

mlthoughts2018 8y ago
Somehow these people are reading Toml files of config? That’s silly.
- andrenth 8y ago
  Do you expect a systems administrator to be familiar with the source of every software he maintains?
  - mlthoughts2018 8y ago
    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.
    - andrenth 8y ago
      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.
      - mlthoughts2018 8y ago
        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.
        andrenth 8y ago
        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.
        mlthoughts2018 8y ago
        > “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). [0]: < https://12factor.net/config https://12factor.net/config >
- com2kid 8y ago
  Non-open source software. Ops teams deploying a service. Programmers who don't know the language a program is written in. Heck what about a config file for a game? If setting the resolution it'd be nice if valid values are shown in the comments. The argument is about comments in JSON btw.
  - mlthoughts2018 8y ago
    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 8y ago
      > 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 8y ago

Somehow these people are reading Toml files of config? That’s silly.

andrenth 8y ago
Do you expect a systems administrator to be familiar with the source of every software he maintains?
- mlthoughts2018 8y ago
  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.
  - andrenth 8y ago
    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.
    - mlthoughts2018 8y ago
      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.
      - andrenth 8y ago
        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.
        mlthoughts2018 8y ago
        > “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). [0]: < https://12factor.net/config https://12factor.net/config >
com2kid 8y ago
Non-open source software. Ops teams deploying a service. Programmers who don't know the language a program is written in. Heck what about a config file for a game? If setting the resolution it'd be nice if valid values are shown in the comments. The argument is about comments in JSON btw.
- mlthoughts2018 8y ago
  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 8y ago
    > 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.