Naming conventions

[Matt Caswell]

On 18/06/2020 13:03, Richard Levitte wrote:
> 
> Okie, if we're going to start this discussion with taking a stand, I
> guess I'll declare that while I initially had the exact same concern,
> I now see this change in a positive light.  This comment from #11997
> got me to change my mind:
> 
>     The already established patterns is a furphy. I'll reword it more
>     precisely: we've done things badly in the past, thus we should do
>     them badly moving forwards. We've always been at war with
>     Eurasia.....oh wrong context, it's Eastasia.
> 

While I can agree with the sentiment here I disagree with the conclusion
that the answer is to change the APIs piecemeal to introduce even more
quirkiness and inconsistency in the APIs.

I'm also not convinced that the currently slightly strange
inconsistencies are worth fixing. Yes, if we were to design it again we
would do it differently. But that does not mean that we have to change
everything to fit into our ideal picture of the way things should be.

To fix it necessarily involves changing the names of a lot of different
functions (how many depends on exactly what convention we eventually
decided upon). Yes, we can lessen the impact by providing backwards
compat macros - but that doesn't mean that a change of name is without
cost. Either applications must change all of the names in their code to
the new form OR they keep the old form and start using the new form for
new code. This pushes the complexity of the name change onto our
downstream application maintainers. They will have all the confusion of
different naming conventions within their application.

It adds further complexity to our documentation. Either we only document
the new forms (which is confusing when application maintainers and
authors see all the old forms being used "out there") - or we have to
ensure all the synonyms are documented everywhere - which is itself
confusing to our users. And our documentation will be at odds with all
the examples and samples and unofficial documentation that our users
undoubtedly use.

I think a wholesale name change can only really be considered if it
brings significant benefits. At the moment I'm struggling to see that
the benefits outweigh the costs.

Even if we decided that we would want to do this, we should also think
twice about doing it in the 3.0 timeframe. We are already pushing a lot
of change onto our users with the change to our architecture. Pushing
more change for dubious benefit doesn't seem like a great idea.

> As for not doing something piecemeal, I actually disagree, I see
> benefit in more than just one person getting their hands dirty (plus
> changing everything in one go may be overwhelming, and would make for
> another huge PR that takes overly much time to get through).  However,
> as strategies go, and if we agree on making the change, we could very
> well create an issue for each affected sub-API and have it point at a
> common page that describes what we agreed upon...  this could be a
> good use of the github wiki tab, for example.

I don't mean piecemeal in the sense of doing it spread over a number of
PRs. I mean piecemeal in the sense of doing it spread over a number of
releases. As far as I can tell #11996 and #11997 were one offs without
any long term strategy in mind to convert the whole API in this way. In
the absence of a strategy we shouldn't be making one off changes like this.

>> There *are* inconsistencies and quirks in our current naming
>> conventions. I am skeptical that now is the time to resolve them given
>> the number of other changes we are already introducing into 3.0.
> 
> When do you see that time being, then?  3.1 (we've talked about it
> being a "cleanup" release)?  4.0?

Perhaps never. But if we do it then either 3.1 or 4.0 could be
considered. I am yet to be convinced that its worth it.

Matt