Legacy Aliases and Wrap-n-Scrap Refactoring

[dreeves]

### Desiderata
- [ ] Have someone read a draft
- [ ] Title image
- [ ] Link preview excerpt
- [ ] Publish
- [ ] Blog blurbs
- [ ] Waggledance
- [ ] Tweet
- [ ] Tip of the day

Example: We're calling an API field "autodata_config" for lack of a better name but maybe later we think of some elegant portmanteau ("autofig"? probably not that) and wish we'd called it that. Here's how to change the a name like that:

---

[TODO: change to slug -> goalname as the example probably]

Consider the API field "initval" and say we want to change it to "vini" (maybe pick a better example where the improvement in the name is obvious). There's a satisfying kind of refactoring for doing that backward-compatibly. The idea is to add a legacy wrapper where old-world-order is converted to new-world-order. So now we can treat everything as if there's only "vini". The documentation and the code all agree: "vini" is all it's called. Except in the legacy wrapper. That's a filter that turns any rogue instances of "initval" to "vini". So no old stuff breaks!

(Backing up, I'm referring to wrap-n-scrap refactoring and I currently do this in Beebrain for deprecated parameter names.)

Does this violate Anti-Postel? If the correct parameter name is "vini" and not "initval" then don't we need to fail loudly on the latter rather than silently convert it to the former? That is indeed an example of what Anti-Robustness dictates. But, sadly, we can't just break all existing API clients. So "initval" will just have to live on as an alias for "vini". At least in APIv1.

I contend that it's worth it to refactor these parameter names (like ones involving "road") and have legacy aliases and deal with the wrap-n-scrap-style isolation of the legacy parameters. That's a fair price to pay for better names.

But you know how I am about names.

---

A later attempt to spell out the proposal:

Say we're renaming some ugly name like optimize_motivation to optivate.

1. Make an appendix of the API docs called "Legacy Aliases" with a preamble about how these endpoints/params are deprecated but still work. Maybe it's in a small font or something so the deprecation is clear. We just need it to be the case that if you come across "optimize_motivation" in old code or the forum or wherever you can grep the API docs and find it. Which brings us to step 2...
2. Add an entry for optimize_motivation: "This was an old name for what's now called optivate [link to optivate's documentation]".
3. In the code, have a legacy translator function that all incoming requests go through.
4. Add a line that effectively does s/optimize_motivation/optivate/g.

Et voila, in all the code (except the legacy translator) and all the docs (except the legacy aliases appendix) it's as if we'd thought of the nicer name from the beginning.

Cognata

• https://github.com/beeminder/beeminder/issues/741

Verbata: principles of software engineering,

[dreeves]

[dreeves]

Oh, slug -> goalname could be the canonical example here. HT Theo.