3 ms·

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 w

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 https://github.com/npm/npm/issues/4482

ordinaryperson 8y ago
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.
- toast0 8y ago
  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.
- TeMPOraL 8y ago
  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.

ordinaryperson 8y ago

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.

toast0 8y ago
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.
TeMPOraL 8y ago
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.