By any other name: What to call similar things

Thursday, 16 January, 2020 — development

On a recent code review, one of my teammates was adding a new branch of code behind a feature flag to adjust how our site search weights potential results.

The existing code had a constant I’ll call RESPONSE_WEIGHT. The new branch added RESPONSE_WEIGHT_NEW. Both would co-exist while the feature flag was present.

Given this is a temporary feature flag that should be retired once the code is determined to be steady-state in production, going back through the code and taking out the feature flag and the old branch will leave RESPONSE_WEIGHT_NEW.

In a few weeks or months, I or another teammate are going to look at RESPONSE_WEIGHT_NEW and wonder what new means. If, we decide to further adjust search result weighting, RESPONSE_WEIGHT_NEW is an outright misleading name.

Appending a name with _new or _old is tempting because it doesn’t require a lot of creativity. It isn’t a great idea, because the new or oldness of it quickly loses context.

If there’s a need to separate functionality or naming by a feature flag, use a suffix like: _2020_Q1, which ties the name to a point in time.

This will also likely leave an earlier name around, and, context dependent, those can also change with a suffix _PRE_2020_Q1, if there’s not already a data quantifier on something.

Then, if and when it comes time to remove the feature flag, the code isn’t populated with now contextless _new entries. Similarly, the code won’t be looking at _new2 or _new_new.

In this case, the pull request feedback resulted in RESPONSE_WEIGHT_2020_Q1, which is more likely to remain an accurate name as long as it lives on in the codebase.