Which is better than the all too common middle ground: writing something once and then not maintaining it. I've been burned many times reading some documentation and thinking I understood until I discovered the code has changed since and the documentation is now wrong.
I'm in favor of documentation. I write it. I get people pointing at what I've written as examples of what everybody should do. However it is a lot of work. I'm constantly looking things over to be sure it still makes sense. I often wonder if it is really worth it. I hope you follow my example and write documentation, but it better feel like a lot of work.
I don't agree with "readable," though. For a simple set of key-values, yes. Once you get into complicated structures, other file formats express the semantics much better.
I think there are many facets to readability. For example, YAML is frequently held up as much easier for humans to read than JSON, but even after many years of reading and writing YAML in various domains, no other format causes me anywhere near as much trouble.
With JSON, I can format the string as I feel makes sense for that specific data structure, while YAML forces me to into specific indentation patterns, and it still causes me to question every time whether the dashes in arrays should be indented or not. And since people frequently template YAML, the strict indentation has caused a bunch of issues for no good reason, including production outages (sure, shouldn't happen with good practices, but there are so many places without good practices!).
Because JSON syntax generally has only one way to represent each data type and almost every data type uses explicit start and end signifiers (except floats and bools, both of which are short and clearly stand out), it's easy to know what the context of every character is both while reading linearly, and when jumping to specific points. Meanwhile YAML has multiple ways to express almost anything, and frequently the only way to tell the current context is to read ahead before jumping back. This is especially terrible for strings due to optional delineation, because almost every bare text could be a keyword (as demonstrated by the Norway problem).
I know this is not most people's experience, but that's because readability is subjective.
If you have a complex configuration you are doing it wrong... Spend some time thinking about you really want and turn it into a simple key-value setup. JSON should feel like it is overpowered and bloated for your needs. (I'd still use JSON because you can find a parser and editor that can handle it, but it should feel overpowered for your needs)
Comments
No, we're just lazy.
Which is better than the all too common middle ground: writing something once and then not maintaining it. I've been burned many times reading some documentation and thinking I understood until I discovered the code has changed since and the documentation is now wrong.
I'm in favor of documentation. I write it. I get people pointing at what I've written as examples of what everybody should do. However it is a lot of work. I'm constantly looking things over to be sure it still makes sense. I often wonder if it is really worth it. I hope you follow my example and write documentation, but it better feel like a lot of work.
Occam's Razor at it's finest. I'm not trying to screw others over. I just want to not write sometimes.
It's readable, it's easy, it gets the job done.
I don't think that's necessarily lazy, it's just efficient
I don't agree with "readable," though. For a simple set of key-values, yes. Once you get into complicated structures, other file formats express the semantics much better.
I think there are many facets to readability. For example, YAML is frequently held up as much easier for humans to read than JSON, but even after many years of reading and writing YAML in various domains, no other format causes me anywhere near as much trouble.
With JSON, I can format the string as I feel makes sense for that specific data structure, while YAML forces me to into specific indentation patterns, and it still causes me to question every time whether the dashes in arrays should be indented or not. And since people frequently template YAML, the strict indentation has caused a bunch of issues for no good reason, including production outages (sure, shouldn't happen with good practices, but there are so many places without good practices!).
Because JSON syntax generally has only one way to represent each data type and almost every data type uses explicit start and end signifiers (except floats and bools, both of which are short and clearly stand out), it's easy to know what the context of every character is both while reading linearly, and when jumping to specific points. Meanwhile YAML has multiple ways to express almost anything, and frequently the only way to tell the current context is to read ahead before jumping back. This is especially terrible for strings due to optional delineation, because almost every bare text could be a keyword (as demonstrated by the Norway problem).
I know this is not most people's experience, but that's because readability is subjective.
If you have a complex configuration you are doing it wrong... Spend some time thinking about you really want and turn it into a simple key-value setup. JSON should feel like it is overpowered and bloated for your needs. (I'd still use JSON because you can find a parser and editor that can handle it, but it should feel overpowered for your needs)
That's what I am saying about my ruby codes as well. Still my boss wanted proper commit messages
Something has gone awry if the config files have a readability and difficulty analogous to that of the codebase.