4 ms·

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

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
    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.
    - com2kid 8y ago
      > 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 // boolean, false leaves tabs alone, true converts spaces to tabs in a config file for my text editor! 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.

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
  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.
  - com2kid 8y ago
    > 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 // boolean, false leaves tabs alone, true converts spaces to tabs in a config file for my text editor! 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.