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

[Sze Howe Koh]

On Sat, Oct 27, 2012 at 1:10 AM, Stephen Kelly <stephen.kelly at kdab.com> wrote:
> I think this is a good initiative. See also
>
> https://codereview.qt-project.org/#change,37727
>
> which is a move in the opposite direction.

Thanks for replying, and for the heads-up; I wasn't aware of Lars'
initiative (which I'll call Proposal 1 below). It would be good if we
could all flesh out the details together on the mailing list. Here's
my take on the situation; the pros/cons of both proposals are compared
against the existing naming system:

//=================================
// Proposal 1: (QNamespace -> QtNamespace)
//=================================

Pros:
- Fewer names to remember


Cons:
- Requires work to maintain source compatibility

- QDoc loses all ability to differentiate between modules and namespaces

- 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


Namespaces that will be changed ('*' = Qt4 namespace):
* QAudio
- QBluetooth
* QDBus
- QDBusUtil
* QGL
- QService
* QSql
* QSsl
* QTest
- QValueSpace


//=================================
// Proposal 2 (QtNamespace -> QNamespace)
//=================================

Pros:
- Fewer names to remember

- QDoc gains ability to differentiate between some new modules and namespaces

- Devs gain ability to #include more namespaces by their names



Cons:
- Requires work to maintain source compatibility


Namespaces that will be changed ('*' = Qt4 namespace):
* QtConcurrent
* QGL (if we rename this to QOpenGL -- but that's a separate discussion)
- QtLocation
- QtMultimedia
- QtMultimedia::MetaData


//=================================
// Analysis and conclusion
//=================================

Proposal 2 has more pros and fewer cons than Proposal 1. Proposal 1's
strength is also present in Proposal 2, and Proposal 2's weakness is
also present in Proposal 1. Furthermore, Proposal 2 involves fewer
changes overall.

Therefore, I contend that Proposal 2 is the better approach: It would
be good to have modules called "QtXyz", and have namepsaces called
"QXyz".


> You wrote that QtBluetooth is an internal namespace, but it is not.
[snip]
>     QtBluetooth::QBluetoothAddress bluetoothAddress;
>     QtContacts::QContact contact;
>     QtOrganizer::QOrganizerCollection organizerCollection;
[snip]
> QtBluetooth uses a namespace for public APIs, but QtLocation does not, for
> example.
>
> The bluetooth classes also already have a Q prefix, so the namespace is
> probably redundant. I'd like to see it removed. If what others want is a move
> toward *more* namespaces, then I think the rest of the former QtMobility
> should get them too (all the stuff that's new in Qt5).

Huh, I didn't realize those namespaces were needed. So, a Bluetooth
Security variable needs to be declared like this:

    QtBluetooth::QBluetooth::Security sec;

That's very unwieldy, no?

+1 for removing redundant namespaces.


> I'm all for the consistent use of namespaces, but before you implement
> everything, it probably makes sense to hear from others too.

Definitely; that's why I'm raising this on the mailing list. I've
asked about this before (in slightly different forms) at
http://qt-project.org/forums/viewthread/20499/ and
http://lists.qt-project.org/pipermail/development/2012-September/006515.html,
but didn't get a strong response. Again, I appreciate your reply here,
Stephen.


Regards,
Sze-Howe