3 ms·
Comments that "self-document" a config file are great. Comments that result in: #Frontend server is called Alpha, and runs HTTPS frontend:"beta":http
by bombcar 3y ago
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 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.