Toml: Tom's Obvious, Minimal Language

Re:Toml: Tom's Obvious, Minimal Language by natefinch on Friday July 13, 2018 @09:03PM (#17528145)

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.

[ Parent | on HN ]

Re:Toml: Tom's Obvious, Minimal Language by DCoder on Saturday July 14, 2018 @03:00AM (#17529193)

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

[ Parent | on HN ]

Re:Toml: Tom's Obvious, Minimal Language by mlthoughts2018 on Saturday July 14, 2018 @06:41PM (#17532781)

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.

[ Parent | on HN ]