[Development] Suggested addition to wiki.qt.io/Coding_Conventions

[Marc Mutz]

Hi,

I'd like to suggest the following addition to the Qt Coding Conventions:

=== Exporting Classes ===

Export polymorphic classes as a whole:

<code>
  class Q_LIB_EXPORT QMyWidget : public QWidget
  { ...
</code>

But don't export non-polymorphic classes that way. Instead, only export the 
following non-inline methods. 

* public
* protected
* private, if called from inline functions (now or in the past)

Rationale: On Windows, symbols from a DLL that don't have inline linkage 
(templates or inline functions have inline linkage) need to be exported for 
clients to link against them, This is what the <tt>Q_*_EXPORT</tt> macros are 
for. On some Unix systems, the macros map to a similar mechanism that 
<em>hides</em> symbols not exported that way, positively affecting startup 
performance and library size.

But exporting the whole class, while convenient, has several drawback:

* it exports symbols that don't need exporting:
** private methods never called from user code
** methods of private nested structs and classes
** inline methods
* exporting inline methods makes MSVC call the library implementation in debug 
builds
** a copy of the function is placed in the library even though the library 
itself may never use it
** exported inline functions can no longer be removed

Thus, exporting the whole class should be the exception, when the implicit 
vtable and the typeinfo objects need to be exported, too. Non-polymorphic 
classes don't have any of these, so exporting the whole class is a case of 
Premature Pessimization.

Thanks,
Marc

-- 
Marc Mutz <marc.mutz at kdab.com> | Senior Software Engineer
KDAB (Deutschland) GmbH & Co.KG, a KDAB Group Company
Tel: +49-30-521325470
KDAB - The Qt Experts