In praise of --dry-run
Something I always want to see in a tool which does anything non-trivial is a --dry-run mode. To be able to know what you’re about to do, before you do it, is a great and wondrous thing, helpful to the novice and the experienced user alike.
But it’s sadly often the case that a tool’s --dry-run is an unloved second-class citizen, prone to drifting out of date or failing to provide all the information you need.
There’s a simple method that keeps you honest, ensures that your --dry-run has all the information the user wants to see, and (an unexpected bonus!) helps make the entire tool more maintainable: use the --dry-run code path as an input to the “execute” code path.
If you have a separate --dry-run code path which is to any extent independent of the main execution flow, then you’ve immediately opted into the huge problem that documentation also tends to suffer: there’s now a way to get your explanations out of sync with what actually happens.
For example, the Wolfram Language is documented almost entirely through interactive notebooks written in the Wolfram Language, and the documentation itself forms a huge test suite that is evaluated as part of the release pipeline. This ensures that a large number of documentation problems actually turn automatically into blockers for release.
