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
