Hacker News new | ask | show | jobs
by natefinch 2891 days ago
IF you have a 500k LOC software project... how the heck is an SRE/devops person going to figure out where in that code a specific configuration item is going to be used? They're not. This is why documentation is essential for projects. You could keep configuration documentation in a separate file... but that only helps for what the config does. It can't help you figure out why Bill (who left the company a while back) set ThreadMax to 650 when he changed the code 6 months ago. There cold be a commit message that references it, but that's more disconnected from the change that just slapping a comment on top that says why.

I agree that code review for configuration changes is necessary. That same code review process can ensure that the comments in the config file are also correct.
2 comments
DCoder 2891 days ago
> It can't help you figure out why Bill (who left the company a while back) set ThreadMax to 650 when he changed the code 6 months ago. There cold be a commit message that references it, but that's more disconnected from the change that just slapping a comment on top that says why.

Also worth noting is that not all config files are committed to version control as-is. If a deployment process bakes the config file from variables, it can be even more disconnected and difficult to find the change.

link
mlthoughts2018 2890 days ago
The size of the project is a red herring in your comment. People document command line options, ENV settings, etc., in huge projects all the time. It has absolutely no bearing on whether comments belong inside of config files.
link