Avoid using aliases for module options

I think we should discuss avoid using aliases. What do you think? At first glance, it makes sense to me.

I agree with this recommendation (and gave similar suggestions in quite a few reviews, and try to avoid them myself as well).

I think the main reason against aliases is that they can quickly lead to confusion: say you’re using both an option and an alias and don’t spot it immediately; or you and a colleague talk about a feature and you’re disagreeing of how it’s called, only to realize that one of you is using an alias.

There are also valid uses for aliases, so it’s definitely not a good idea to completely forbid them. But recommending to avoid them is still a good thing, to make folks at least think twice before adding a new one!

3 Likes

The PR doesn’t forbid aliases completely, it says:

Generally avoid using aliases.

Generally is important here :wink:

And it also says:

Consider using them temporarily in exceptional cases like typos or inappropriate words in the original argument name with deprecation and subsequent removal of the original one using the deprecated_aliases attribute.

So it still allows using aliases. The PR allows to use aliases if there’s a valid use case.

3 Likes

Aliases are not added because of “bad naming”, it helps to manage compatibility during various changes. For example in Podman we have arguments that fit Podman args, which are VERY changing in time, but also tries to have compatibility with Docker args. And every other software changes its arguments with aliases, that’s a real life.
Misuse and abuse can destroy any good idea, it doesn’t mean the idea was wrong. I’m totally for deprecated_aliases shortcut though, which will save time of working on deprecation messages.

I think the idea of providing guidance around best practices for aliases is good, but I do not find the way it’s currently phrased helpful. I would go for something more like this:

Excessive use of aliases can make module interfaces confusing, so we recommend adding them only when necessary. If you are updating argument names to fix a typo or improve the interface, consider moving the old names to deprecated_aliases rather than keeping them around indefinitely.

6 Likes

@flowerysong your wording SGTM, would you like to suggest the change in the PR so that you’ll be a co-author? If you miss this message anyhow, I’ll update it myself in a day or two. Thanks!