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

[Knoll Lars]

On Oct 27, 2012, at 6:08 PM, Sze Howe Koh <szehowe.koh at gmail.com> wrote:

> 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

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.
> 
> - 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.
> 
> 
> 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.

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.

The one thing that counts stronger is that the change towards QtNamespace would have a larger chance of introducing source incompatibilities against Qt 4.x.

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

Because our SC policy and since we're close to the next beta and want to minimise changes I agree. But I would have preferred the QtNamespace solution.
> 
> 
>> 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.

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.

Cheers,
Lars

> 
> 
>> 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
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development