[Development] Some Qt3D feedback

[Sze Howe Koh]

First, a big thanks to Stephen for bringing these issues to the ML's attention.

The topic of namespacing has been raised a few times before, but
discussions faded without us reaching any solid conclusions:
http://comments.gmane.org/gmane.comp.lib.qt.devel/13176

I think the disagreements we have on this topic stem from the desire
to uphold two different values that tread on each others' toes a bit:
* Progress (related to replacing old things with new and better ones)
* Consistency (related to familiarity and intuitiveness)

Let's aim to achieve both without unnecessarily sacrificing either.
This means being willing to try new things, but also means applying
the findings from these trials to the entire Qt framework as uniformly
as possible.


On 12 June 2015 at 16:21, Sean Harmer <sean.harmer at kdab.com> wrote:
> On Thursday 11 June 2015 23:15:20 André Pönitz wrote:
>> Specifically, for item #6:
>>
>>     [Stephen]
>>
>>     > Qt3DParamter might be better *and* more consistent.
>>     > Similar applies to other classes.
>>
>>     [Sean]
>>     It's precisely because of these kinds of issues that we decided to use
>>     namespaces in Qt3D rather than the poor-man's prefix name spacing.
>>     [...]
>>     Name spaces are supported everywhere these days so why not just use
>>     them, especially in a new add-on module?
>>
>> That's exactly the kind of situation I was referring to in my previous
>> mail: This is *intentionally* introducing API inconsistency. It does not
>> really matter to me whether "poor-man's prefix name spacing" is
>> unfashionable or "we" consider it bad. It is simply *inconsistent* with
>> more than 200 of existing exported QQuick*, QSG* and QQml* classes.
>
> The majority of those QQuick*, QSG*, and QQml* classes are not exported or
> documented as internal so the 200 number is overstated.
>
> Also, as Marc pointed out, those class names are themselves inconsistent with
> other classes within QtCore, QtNetwork, QtGui etc. As I replied earlier, once
> you add a using namespace Qt3D to a translation unit the Qt3D actually looks
> more consistent with other parts of Qt than using QQuick* etc. with the
> proviso that you need to disambiguate in the case of collisions.
>
> Furthermore, it is inconsistent to want to push forwards with the allowable
> set of C++ 11/14/whatever features which will mean dropping support for older
> compilers and platforms, yet denying the ability to evolve our API beyond the
> 1990's paradigm. Dropping support for older compilers is a much harder pill to
> swallow than asking people to use a namespace in a new addon module.
>
> I'm not arguing that namespaces should be used because they are fashionable.
> I'm arguing they should be used because this is the intended use case of a
> very mature language feature. If we can't try new things out in new addon
> modules, then where can we try them?

I agree that we should try new things to improve on the old ways. The
important thing is that we convert the trial results into solid
written guidelines, so that we don't spend time discussing this again
come Qt 5.6 or 5.7.

I propose the following, with the hope that we formalise our decisions
at http://wiki.qt.io/Coding_Conventions for future reference.



(1) Let's commit to extracting (and following) solid guidelines from
this experiment.

By the time we reach the Qt 5.6 feature freeze, we need to have clear
directions in the wiki on (i) what new modules in Qt 5.6+ should look
like, and ideally (ii) what all modules in Qt 6 should look like. Do
we convert QQmlComponent to QtQml::QComponent, or convert
Qt3D::QComponent to Q3DComponent?



(2) Let's decide on how to name namespaces.

We recently got new namespaces with both the "Q" prefix
(QWebSocketProtocol) as well as the "Qt" prefix (QtWin, QtAndroid,
Qt3D). Which shall it be?



(3) Let's decide on how namespaces and #include headers should work
with each other.

There are a few sub-issues here:

a) We already have weird headers like <QtConcurrentRun>, and we almost
ended up with weird headers like <QWinFunctions> for the QtWin
namespace: https://codereview.qt-project.org/#/c/69108/ We need ground
rules on how to design header names around namespace names.


b) Should namespaces be #includable? Some are (QtWin, QTest), some
aren't (Qt3D).


c) At Qt 5.0's launch, the advice given to users was "Only #include
the class name, not the module name". In other words, use "#include
<QQmlComponent>", not "#include <QtQml/QQmlComponent>. However, if
class names are allowed to be non-unique, this advice must change. I
guess we revert to the old way of #including the module name along
with the class name?



(4) Let's decide on how to name QML types.

Spot the odd one out:

- (Qt Multimedia module) QCamera class -> Camera QML type
- (Qt 3D Core module) Qt3D::QCamera class -> Camera QML type
- (Qt QML module) QQmlComponent class -> Component QML type
- (Qt 3D Core module) Qt3D::QComponent class -> Component3D QML type



(5) Let's decide on the relationship between C++ modules and QML modules.

C++ classes are split between between "Qt 3D Core" and "Qt 3D
Renderer". QML types are not (everything is under "Qt3D". Do we want
this asymmetry?



(6) Let's finalize: Is it "Qt 3D Render" or "Qt 3D Renderer"?

All other modules use:
* #include <QtModuleName> for the module-wide include
* QT += modulename for the .pro file

However, we currently have a "Qt 3D Render" module with:
* #include <Qt3DRenderer>
* QT += 3drenderer

Let's stick to existing conventions here.



(7) (Unimportant in itself, but related to a few items above) Let's
decide on the definition of "module".

This word is seriously overloaded (and sometimes abused, e.g. "QtBase
module"). Anyway, Active Qt and Qt 3D are the 2 "modules" in Qt that
have "sub-modules". How should "module" be defined?

One possibility is: 1 module = 1 .pro file entry = 1 DLL (excluding
plugins), meaning that "QAxContainer", "QAxServer", "Qt 3D Core", "Qt
3D Renderer", and "Qt 3D Input" are modules, while "Active Qt" and "Qt
3D" are "module groups".



What do you think?


Regards,
Sze-Howe