2 ms·
Comments are absolutely vital, in my opinion; especially for config files. I don't like XML, YAML, or JSON. If I am doing server-side PHP, my config files are
by ChrisMarshallNY 3y ago
Comments are absolutely vital, in my opinion; especially for config files.
I don't like XML, YAML, or JSON.
If I am doing server-side PHP, my config files are executable PHP. It's my responsibility to make sure they can't break the system too much.
If I am doing host-side stuff (like Swift Package Manager), I prefer executable Swift files.
But I cut my teeth on BNF[0], and X.500[1]. They worked well, but were painful. They make YAML look good.
[0] https://en.wikipedia.org/wiki/Backus–Naur_form https://en.wikipedia.org/wiki/Backus–Naur_form
[1] https://en.wikipedia.org/wiki/X.500 https://en.wikipedia.org/wiki/X.500
- bombcar 3y agoComments 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 3y agoI 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/master/Tests/config/LGV_MeetingServer-Config.php https://github.com/LittleGreenViper/LGV_MeetingServer/blob/m...
- bombcar 3y agoBy "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.
- somat 3y agoI like how the openbsd project does it. They have a parse.y that sort of gets traded around and joins new projects. Nothing super formal but it does mean most openbsd service configuration feels like each other. but each config is tailored to it's application. and being properly parsed the error messages can be better. In fact that is my biggest beef about yaml, I mainly use it in the context of ansible, and the parsor usually has no clue where in the file the error actually is. You have to depend on remembering where you last edited to actually find the error. My other big problem with yaml is that the ansible context is trying very hard to make it a programing language... And while it is an okish config language it is a terrible programing language. In fact this is a common problem with many complex environments. They want to try and push this complicated setup into a config file and claim "look it is easy, no programing required" when really what they have done is to push a programing situation into the worlds worst programing language. see also: xslt
- ChrisMarshallNY 3y ago> see also: xslt Not without a trauma therapist on speed-dial.
- 20after4 3y agoI get through most days without remembering that xslt exists and I like it that way.