Coming up with a naming convention for things like metadata keys, customer HTTP headers, or log tags; and not writing it down and sharing it with others, is a mistake I’m paying for in spades at the moment.
A little while ago, when we were setting up Stripe and it came time to decide how metadata keys should look, I thought it would be enough to come up with a style in my head (e.g. snake case with a particular prefix) and simply start using it. I guess I was expecting that others would follow it, simply because they would be motivated to maintain the observed style, with the keys I were defining being a bit of an example here.
Well, I now know that not only did this not happen, but when someone does want to know how these names should look (and I include myself here) there’s no definitive guide available to refer to. The result: no convention at all. Different cases, keys without a prefix, etc. Not be a huge problem, but being unable to rely on a convention does mean more cognitive load when it comes time to figuring out how a name is expected to be formed. Plus, it just looks untidy.
I guess it would have been a good idea to document it somewhere. Doing this is not being overly specific or dictating convention from above. It doesn’t have to be as elaborate as an IETF standards: just a few paragraphs and examples that is accessible to everyone. And if others disagree with the proposed convention, then work it through until everyone is happy with it.
I’ll try to remember this for next time.
P.S. More services really need to support user-defined metadata fields like Stripe does.