[Development] Consistency in Qt headers (extends: 'renaming all QWindow properties that have "window" in them')

[Sze Howe Koh]

On Mon, Oct 29, 2012 at 5:45 PM, Knoll Lars <Lars.Knoll at digia.com> wrote:
>> - QDoc loses all ability to differentiate between modules and namespaces
>
> In principle that's fixable in qdoc. If we were to start from scratch, I think QtNamespace would be more consistent, as it's the same as the module name. But it's certainly the bigger change.

I see. My criteria for "consistency" was, "does this match Qt 4's
majority?" -- which mostly had QtModule and QNamespace

I think QtNamespace would work better if there was a tight one-to-one
mapping between module and namespace. We currently don't have this
though, as the Qt Multimedia module has both a Q(t)Multimedia and a
QAudio namespace. For the sake of generating ideas for Qt 6, which of
the following do you think is best?

Namespaces for the Qt Multimedia module:
1) QMultimedia + QAudio + QMediaMetaData (current plan)
2) QtMultimedia + QtAudio + QtMediaMetaData (simple change from
QNamespace to QtNamespace)
3) QtMultimedia + QtMultimedia::Audio + QtMultimedia::MetaData (show hierarchy)
4) Merge everything into QtMultimedia
5) Something else


Re-doing QDoc would be a massive task too, I'd imagine. I also can't
think of a simple way for QDoc to generate links to both module and
namespace with the same name -- candidates I can think of are:
- Manual linking (slow, hard to maintain)
- Use explicit qualifiers at all times, e.g. "the QtMultimedia
module", "the QtMultimedia namespace"

Design For Testability is a well-regarded pattern, and I think Design
For Documentability is also worthwhile :)


>> - Devs lose all ability to #include namespaces by their names, as the
>> headers are already taken by the modules. Possible workarounds:
>> --- Create new namespace header names: This negates the pros of the proposal
>> --- #include the whole module: This is bad for large projects
>
> I think this is a minor problem in practice, as there should be few places where you need to explicitly include the namespace without other headers of the module.

That's true. This argument by itself isn't enough for making the
decision. But it's one of the little side benefits that can help tip
the scales when combined with other considerations.

I did use QAudio's enums independently in my last project, when
implementing a custom audio processor -- it provided a tidy way to
interface with Qt's own audio classes, which were only a small part of
my system.


> I do believe there would be value in having the namespace names consistent with the module names. The include and qdoc arguments are IMO both rather weak.
>
> There's an additional argument against QNamespace IMO: The simple fact that you then have the same naming convention as for classes.

When writing code, the way I use namespaces is much more similar to
how I use classes, than to how I use modules.

I actually like the idea of being able to treat namespaced functions
the same as static member functions (and namespaced enums the same as
class enums):

    #include <QTest>  // namespace
    #include <QString> // class

    char *data_cstr = QTest::toString(data);
    QString data_qstr = QString::fromLatin1(data_cstr);


As a programmer, I feel this style makes my code tidier (with no mix
of "QAbc::Foo" and "QtXyz::Bar"). However, I realize that this is a
purely personal preference, and I can see why others (e.g. systems
architects) would prefer a clear distinction between namespaces and
classes. Conceptually, namespaces are more similar to modules, than to
classes, after all.


> Yes, that's wrong. Feel free to clean it up, but it's not urgent since it's not part of the 5.0 release.

I just remembered Thiago's email
(http://lists.qt-project.org/pipermail/development/2012-October/007099.html).

I'll begin cleaning up the selected Qt 5.0 modules first, then move on
to the others later.


Regards,
Sze-Howe