3 ms·

In our JSON config files we do: { "ConfigKeyComment": "This is for blah blah blah", "ConfigKey": "Foo" } Obviously this wouldn't work in all cases (you're

In our JSON config files we do: { "ConfigKeyComment": "This is for blah blah blah", "ConfigKey": "Foo" } Obviously this wouldn't work in all cases (you're putting more work on your parser to interpret unused keys basically), but if we're talking config files specifically, I see this as an acceptable approach since there's little chance you'll be parsing such files more than once each (plus, writing a simple tool to strip the comments out would be very trivial).

biztos 8y ago
I've tried something similar but found it way too painful if the comments need to be long... # Never enable this config, because if you do the space-time # continuum will collapse into itself and the cloud servers # will disappear in a puff of steam. However, if you really # must enable it, remember that it's boolean and go read # TICKET-8675309 for the extensive list of side effects. TurboFactorRenoberation = false ...so people just end up writing stuff like: { "ConfigKeyComment": "TICKET-8675309", "ConfigKey": "TurboFactorRenoberation", "ConfigVal": false } [edit]: formatting
- mschuster91 8y ago
  That's not JSON anymore, that's pretty much enough to be considered a unique DSL. Scary that this is more or less required.
  - zaphar 8y ago
    Almost all applications evolve their config files into unique DSLs over time. They may choose a generic serialization for the DSL's AST but it will end up being an underspecified application specific DSL regardless.
lostctown 8y ago
Interesting approach. Maybe I'm lazy but avoiding increasing cost to commenting is one of the few absolutes I abide by. Often I find myself tired after a long stretch of code, trying to convince myself that's it's understandable on it's own. This is one of those systematic rules I have to enforce to shutdown my lazy lizard brain. edit: But I can see how highly structured comments could actually come in handy as well for viewing configs in a gui

biztos 8y ago

I've tried something similar but found it way too painful if the comments need to be long... # Never enable this config, because if you do the space-time # continuum will collapse into itself and the cloud servers # will disappear in a puff of steam. However, if you really # must enable it, remember that it's boolean and go read # TICKET-8675309 for the extensive list of side effects. TurboFactorRenoberation = false ...so people just end up writing stuff like: { "ConfigKeyComment": "TICKET-8675309", "ConfigKey": "TurboFactorRenoberation", "ConfigVal": false } [edit]: formatting

mschuster91 8y ago
That's not JSON anymore, that's pretty much enough to be considered a unique DSL. Scary that this is more or less required.
- zaphar 8y ago
  Almost all applications evolve their config files into unique DSLs over time. They may choose a generic serialization for the DSL's AST but it will end up being an underspecified application specific DSL regardless.

lostctown 8y ago

Interesting approach. Maybe I'm lazy but avoiding increasing cost to commenting is one of the few absolutes I abide by. Often I find myself tired after a long stretch of code, trying to convince myself that's it's understandable on it's own. This is one of those systematic rules I have to enforce to shutdown my lazy lizard brain. edit: But I can see how highly structured comments could actually come in handy as well for viewing configs in a gui