On: XML is better than YAML – Hear me out

[bombcar]

Comments that "self-document" a config file are great.

Comments that result in:

    #Frontend server is called Alpha, and runs HTTPS
    frontend:"beta":http

cause me to die.

[ChrisMarshallNY → bombcar]

I find “self-documentation” often doesn’t actually work. It’s great in theory, but often falls down, in practice.

I tend to preface my config stuff with fairly substantial comment blocks that discuss the reasoning behind the configuration.

Here’s an example: https://github.com/LittleGreenViper/LGV_MeetingServer/blob/m...

[bombcar → ChrisMarshallNY]

By "self-documenting" I mean things like:

    # Diff for interactive merges.
    # %s output file
    # %s old file
    # %s new file
    merge="sdiff --suppress-common-lines --output='%s' '%s' '%s'"

it's useful the first time you dive in, not having to read the man page. But over time, the comments can get out of sync especially if you don't carefully merge in the package-maintainer's version every update.