Policy on forward declarations for things from external libraries

[Harald Sitter]

On Fri, Jul 31, 2020 at 5:56 PM Vlad Zahorodnii <vlad.zahorodnii at kde.org> wrote:
>
> Howdy,
>
>  From time to time, I find myself in a situation where a code reviewer
> suggests to replace #include <QFoobar> with the corresponding class
> forward declaration. Such discussions usually get us nowhere because
> neither the code reviewer nor I mind to seek for a compromise. A policy
> would prevent wasting time on such discussions.
>
> Note that I used Qt/QFoobar only as an example. Similar logic can be
> applied to other libraries as well. For example, libxcb or libexif, etc.
>
> The good thing about forward declarations is that they can reduce the
> compilation time quite significantly.
>
> The bad thing about it is that we must guarantee that the definition of
> QFoobar in the external library won't change. For example, QFoobar won't
> move into an inline namespace all of sudden, etc.
>
> I propose to add a paragraph in [1] saying whether it is okay to add
> forward declarations for things from external libraries.
>
> Any thoughts or suggestions?

IMHO it'd only blow up the policy. This has more to do with API design
than with forward declaration. As such this is kind of covered by the
policy on d-pointers and Qt's policy on being minimal. Most API will
not want any headers or objects other than Qt, cpp and libc in
*public* headers anything beyond that very very very likely belongs in
a Private class. In particular when you have reason to believe that
the authors of the library may not be able to keep their compatibility
for as long as we do or to the degree we do. Or put the other way
around: if the upstream's compatibility promise isn't at least as good
as our own then it has no business being part of our public API,
forward decl or not.

With that in mind the existing policy on forward decls is fairly clear
on the matter: use forward decls whenever possible. Forward declaring
has very practical advantages that are always worth having.

HS