The motivation of that rule was to break our habit of using "OO" as jargon to mean "use the methods on an explicit object rather than letting pyplot keep track of the current axes".

I think we should clarify that if we are talking about the concept of object orientation as a programming paradigm I think that should be exempt from the style guide, but if we are referring to our code in the context of telling users how to use it we should call it "explicit" or similar. e.g.

• Bad: "We suggest using the OO-style, rather than pyplot, when writing functions"
• Good: "We suggest using the explicit interface, rather than the implicit interface, when writing functions"

But I'm not clear why it is a bad "habit" to call it the OO interface.

Outside of the context of these discussions I wouldn't know what was meant by an explicit interface versus an implicit one. Those are pretty jargony terms. Sure OO is jargony, but it sounds better than "not pyplot" and it has the advantage of making it clear that everything is considered an object.

I think we still need a better name for the concept. “Object oriented” is very technical and I assume isn’t very clear for users without a software development background. One suggestion that was brought up was “explicit” (referring that you explicitly specify the Axes, whereas in pyplot the Axes is implicit). I’m still not quite happy with that terminology and suggest we look further.

Yes, "Object oriented" is a technical term, but a) it indicates what is being done in a relatively easy-to-infer way, and b) it is easily searchable on a search engine. It is way harder to get the right meaning by looking up "explicit" (in fact don't ask your children to look up "explicit", unless you want to have a long talk with them about what they may find on the internet).

Google "explicit program interface" and google "object oriented" and judge which is more parsable by someone who has never taken a computer science course.

I guess an alternative may be "hierarchal interface" versus "top-level interface"? Maybe there are other candidates....

I agree that "explicit" is way too vague.

Problem with "object oriented": While it's a well defined term, it's not the essence of what we want to communicate. All we want to say is "Create one/mutliple Axes with plt.subplots() (and the like) and call methods on the Axes object to add add data and configure the plot." While technically this uses OOP in the background, you don't need to know anything about OOP concepts (classes, encapsulation, composition, inheritance, polymorphism, ...). Even more, knowing OOP alone still does not provide you any guidance what we mean by "use the OOP interface of Matplotlib". That still needs the context of the above explanation.

I suggest using someting like "pyplot" vs. "Axes" in the term we choose: What the user types is

plt.plot()
plt.xlabel()

vs.

ax.plot()
ax.xlabel()

Having plt and ax reflected in the naming seems a good approach. A very simple terminology could be

• pyplot interface
• Axes interface

While this disregards some details (You do some things on Figure or Axis objects, you still need to start with plt.subplots()), I think the simplicity could be worth it.

Having plt and ax reflected in the naming seems a good approach. A very simple terminology could be

• pyplot interface
• Axes interface

Thats a pretty good suggestion!

I agree that "explicit" is way too vague.

"explicit" is not explicit enough ? 🤣

I agree "pyplot interface" and "Axes interface" is a good suggestion.

I think an enduring problem with the "pyplot interface" terminology is that you're meant to start every figure creation in explicit/OO style by importing matplotlib.pyplot and calling ... a pyplot function (figure or subplots). I've seen confusion about this before.

And "Axes" interface is confusing in the converse way: you never actually call the Axes constructor.

I think I originally proposed "explicit" and "implicit" (though @tacaswell and I may have a multiple discovery claim) and still like them because I think they communicate, at least somewhat effectively, why you advocate for the explicit/OO interface. (I also 100% +1 @timhoffm's articulation of the case against "OO". I would expect a some people might read "prefer the OO interface" as participation in one of those pedantic "OO is great!" / "OO is terrible!" arguments which is neither here nor there.)

But "explicit interface" and "implicit interface" are indeed less forthcoming about how they map onto the actual matplotlib objects/functions that you invoke. What if "explicit" and "implicit" modified a matplotlib noun, like "explicit axes", "implicit axes"? Or "figure", or "plot"?

I also continue to think that this is such a pervasive source of confusion/difficulty/overestimation of complexity with matplotlib that thinking bigger about how to improve the situation would be really helpful (but out of scope for this discussion, I guess).

The confusion that arises because 99.99% of users need to start a figure with pyplot is planned to be removed by moving those top-level functions up into the main name space or different module (import matplotlib as mpl; fig = mpl.figure(...)). That leaves spinning up a GUI as a second thing that pyplot does - @tacaswell has made significant progress on mpl_gui which will be where the window manager etc are spun up. That will leave pyplot calling those things for backcompatability, and doing implicit gcf/gca/gco management. The hope is that users will no longer need to call pyplot.

Of course the problem with that plan is 15 years of documentation, but....

That roadmap is a little bit aside from the current issue, but perhaps we don't need to fix the current docs until we know what the situation will be in a few months.

Oh hey, that's really cool! Well, yes, with approximately 1M code snippets out there using plt.something, its half-life will be quite long, but I think that's great news.

BTW I may have given this feedback before, but it would be really helpful for the matplotlib docs to have a canonical target that clearly explains:

• what this "OO" vs "pyplot" (along with synonyms) thing is all about
• what are the relative advantages of each style, along with best practice recommendations
• why you can have a hard time if you don't understand the distinction

There is this page but I have to say ... it's quite brief, abstract, and jargonful. I don't really see how I could drop that link as a comment on a StackOverflow post where someone is really confused by what happens when they call plt.xticks (or whatever) and expect it to clarify things for them.

The discussion in this issue is important too — clear and consistent terminology will help — but without an actual explanation of what the terms mean, it's kind of a conversation about the conventions of a secret language.