Hi,

as one of the people complaining to Marc on the change:

I really don't like "undocumented API can change", especially not for members. Using such a member is one tab completion away

I'm willing to make some amends (function which can't be used without also using private API, like a function taking an instance of a private class), but I think the general guide line should IMHO be: Use the normal deprecation workflow for them.

To respond to Volker's point
> I (or my IDE) might find something promising in some public header, but if I have no information about what the author of that thing is promising me, should I use it in my code

Well, there's Hyrum's law. And I'm guilty of breaking user code by changing the semantics of under-specified code myself, but I'd still argue that we should avoid that as much as possible.

Lastly, I'd push against putting undocumeted/internal functions into public headers to begin with to reduce that friction in the future. Or if we end up with a more nuanced stance like "function which can't be used without also using private API", consistently use the "Badge pattern" [1] for them, to make it impossible for anyone to use them outsider of their intended context.

Kind regards,
Fabian

[1] https://awesomekling.github.io/Serenity-C++-patterns-The-Badge/

On 10.07.25 14:37, Marc Mutz via Development wrote:
Hi,

I'm coming back to this thread, because this conclusion:


Confidential
On 18.03.24 16:28, Volker Hilsheimer wrote:
[...]

to use those APIs you have to read the code. And
then you’ll see that they are either undocumented, or documented as
\internal.

You can still use them, but you know that they might change.
[...]

is being challenged for a recent change of mine that renamed
undocumented QArrayData::ref_ to m_ref¹. There's a growing pile of reviewers
that don't like the change, mainly because it breaks QtC (a fix is
available already², there's also a revert³ of the original change)

¹ https://codereview.qt-project.org/c/qt/qtbase/+/651494
² https://codereview.qt-project.org/c/qt-creator/qt-creator/+/660083
³ https://codereview.qt-project.org/c/qt/qtbase/+/660072

With the above rule, undocumented is equivalent to private. In particular,
you have to assume that undocumented API changes at any time.

We now see how loud the outcry is when such changes, routinely done
every week, happen to hit one of our own tools with a vocal developer base.

Do we still uphold the rule? I will bow to the decision, but either the
change is allowed alongside all others, or none are. It can't be that
we apply double standards.

Thanks,
Marc

--
Marc Mutz <marc.m...@qt.io> (he/his)
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B


--
Fabian Kosmale
Manager R&D

The Qt Company GmbH
Erich-Thilo-Str. 10
D-12489 Berlin
fabian.kosm...@qt.io
+49 1638686070

--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Reply via email to