View source for Coding-Conventions

[[Category:Developing_Qt::Guidelines]]

[toc align_right=&quot;yes&amp;quot; depth=&quot;3&amp;quot;]

= Qt Coding Conventions =

This is an overview of the high-level coding conventions we use when writing Qt code.<br />See [[Qt_Coding_Style]] for the lower-level conventions.

== C++ features ==

* Don't use exceptions
* Don't use rtti (Run-Time Type Information; that is, the &lt;code&amp;gt;typeinfo&amp;lt;/code&amp;gt; struct, the &lt;code&amp;gt;dynamic_cast&amp;lt;/code&amp;gt; or the &lt;code&amp;gt;typeid&amp;lt;/code&amp;gt; operators, including throwing exceptions)
* Use templates wisely, not just because you can.

Hint: Use the &lt;code&amp;gt;compile&amp;lt;/code&amp;gt; autotest to see whether a C++ feature is supported by all compilers in the test farm.

== Conventions in Qt source code ==

* All code is ascii only (7-bit characters only, run &lt;code&amp;gt;man ascii&amp;lt;/code&amp;gt; if unsure)
** Rationale: We have too many locales inhouse and an unhealthy mix of UTF-8 and latin1 systems. Usually, characters &gt; 127 can be broken without you even knowing by clicking SAVE in your favourite editor.
** For strings: Use &lt;code&amp;gt;&lt;/code&amp;gt; (where &lt;code&amp;gt;nnn&amp;lt;/code&amp;gt; is the octal representation of whatever character encoding you want your string in) or &lt;code&amp;gt;&lt;/code&amp;gt; (where &lt;code&amp;gt;nn&amp;lt;/code&amp;gt; is hexadecimal). Example: &lt;code&amp;gt;QString s = QString::fromUtf8(&quot;13\005&amp;quot;);&lt;/code&amp;gt;
** For umlauts in documentation, or other non-ASCII characters, either use qdoc's command or use the relevant macro; e.g. for &amp;uuml;
* Every QObject subclass must have a &lt;code&amp;gt;Q_OBJECT&amp;lt;/code&amp;gt; macro, even if it doesn't have signals or slots, otherwise &lt;code&amp;gt;qobject_cast&amp;lt;/code&amp;gt; will fail.
* Normalize the arguments for signals + slots (see &lt;code&amp;gt;QMetaObject::normalizedSignature&amp;lt;/code&amp;gt;) inside connect statements to get faster signal/slot lookups. You can use &lt;code&amp;gt;$QTDIR/util/normalize&amp;lt;/code&amp;gt; to normalize existing code.

=== Including headers ===

* In public header files, always use this form to include Qt headers: &lt;code&amp;gt;#include &lt;QtCore/qwhatever.h&amp;gt;&lt;/code&amp;gt;. The library prefix is neccessary for Mac OS X frameworks and is very convenient for non-qmake projects.
* In source files, include specialized headers first, then generic headers. Separate the categories with empty lines.

<code><br /> #include &lt;qstring.h&amp;gt; // Qt class

#include &lt;new&amp;gt; // STL stuff

#include &lt;limits.h&amp;gt; // system stuff<br /></code>

* If you need to include &lt;code&amp;gt;qplatformdefs.h&amp;lt;/code&amp;gt;, always include it as the '''first''' header file.
* If you need to include private headers, be careful. Then use the following syntax. It doesn't matter in which module or directory whatever_p.h is in.

<code><br /> #include &lt;private/whatever_p.h&amp;gt;<br /></code>

* If you need to include &lt;code&amp;gt;qt_x11_p.h&amp;lt;/code&amp;gt;, always include it as the '''last''' header file.

=== Casting ===

* Avoid C casts, prefer C++ casts (&lt;code&amp;gt;static_cast&amp;lt;/code&amp;gt;, &lt;code&amp;gt;const_cast&amp;lt;/code&amp;gt;, &lt;code&amp;gt;reinterpret_cast&amp;lt;/code&amp;gt;)
** Rationale: Both reinterpret_cast and C-style casts are dangerous, but at least reinterpret_cast won't remove the const modifier
* Don't use &lt;code&amp;gt;dynamic_cast&amp;lt;/code&amp;gt;, use &lt;code&amp;gt;qobject_cast&amp;lt;/code&amp;gt; for QObjects or refactor your design, for example by introducing a type() method (see QListWidgetItem)
* Use the constructor to cast simple types: &lt;code&amp;gt;int(myFloat)&lt;/code&amp;gt; instead of &lt;code&amp;gt;(int)myFloat&amp;lt;/code&amp;gt;
** Rationale: When refactoring code, the compiler will instantly let you know if the cast would become dangerous.

=== Compiler/Platform specific issues ===

* Be extremely careful when using the questionmark operator. If the returned types aren't identical, some compilers generate code that crashes at runtime (you won't even get a compiler warning).

<code><br /> QString s;<br /> return condition ? s : &quot;nothing&amp;quot;; // crash at runtime - QString vs. const char *<br /></code>

* Be extremely careful about alignment.
** Whenever a pointer is cast such that the required alignment of the target is increased, the resulting code might crash at runtime on some architectures. For example, if a &lt;code&amp;gt;const char '''&lt;/code&amp;gt; is cast to an &lt;code&amp;gt;const int'''&lt;/code&amp;gt;, it'll crash on machines where integers have to be aligned at a two- or four-byte boundaries.
** Use a union to force the compiler to align variables correctly. In the example below, you can be sure that all instances of &lt;code&amp;gt;AlignHelper&amp;lt;/code&amp;gt; are aligned at integer-boundaries.

<code><br /> union AlignHelper {<br /> char c;<br /> int i;<br /> };<br /></code>

* Anything that has a constructor or needs to run code to be initialized cannot be used as global object in library code, since it is undefined when that constructor/code will be run (on first usage, on library load, before main() or not at all). Even if the execution time of the initializer is defined for shared libraries, you'll get into trouble when moving that code in a plugin or if the library is compiled statically:

<code><br /> // global scope<br /> static const QString x; // Wrong - default constructor needs to be run to initialize x<br /> static const QString y = &quot;Hello&amp;quot;; // Wrong - constructor that takes a const char * has to be run<br /> QString z; // super wrong<br /> static const int i = foo(); // wrong - call time of foo() undefined, might not be called at all<br /></code>

Things you can do:

<code><br /> // global scope<br /> static const char x[] = &quot;someText&amp;quot;; // Works - no constructor must be run, x set at compile time<br /> static int y = 7; // Works - y will be set at compile time<br /> static MyStruct s = {1, 2, 3}; // Works - will be initialized statically, no code being run<br /> static QString '''ptr = 0; // Pointers to objects are ok - no code needed to be run to initialize ptr<br /></code>
<br />Use &lt;code&amp;gt;Q_GLOBAL_STATIC&amp;lt;/code&amp;gt; to create static global objects instead:
<br /><code><br /> Q_GLOBAL_STATIC(QString, s)
<br /> void foo()<br /> {<br /> s()<s>&gt;append(&quot;moo&amp;quot;);<br /> }<br /></code>
<br />Note: Static objects in a scope are no problem, the constructor will be run the first time the scope is entered. The code is not reentrant, though.
<br />* A &lt;code&amp;gt;char&amp;lt;/code&amp;gt; is signed or unsigned dependent on the architecture. Use &lt;code&amp;gt;signed char&amp;lt;/code&amp;gt; or &lt;code&amp;gt;uchar&amp;lt;/code&amp;gt; if you explicitely want a signed/unsigned char. The following code will break on ppc, for example:
<br /><code><br /> char c = 'A';<br /> if (c &lt; 0) { … } // WRONG</s> condition is always true on platforms where the default is unsigned char<br /></code>
<br />''' Avoid 64-bit enum values.<br />'''''' The aapcs embedded ABI hard codes all enum values to a 32-bit integer.<br />'''''' Microsoft compilers don't support 64-bit enum values. (confirmed with Microsoft ® C/C++ Optimizing Compiler Version 15.00.30729.01 for x64)

=== Aesthetics ===

* Prefer enums to define constants over &lt;code&amp;gt;static const int&amp;lt;/code&amp;gt; or defines.
** enum values will be replaced by the compiler at compile time, resulting in faster code
** defines are not namespace safe (and look ugly)
* Prefer verbose argument names in headers.
** Most IDEs will show the argument names in their completion-box.
** It will look better in the documentation
** Bad style: &lt;code&amp;gt;doSomething(QRegion rgn, QPoint p)&lt;/code&amp;gt; - use &lt;code&amp;gt;doSomething(QRegion clientRegion, QPoint gravitySource)&lt;/code&amp;gt; instead
* When reimplementing a virtual method, do not put the `virtual` keyword in the header file.<br />On Qt5, annotate them with the &quot;Q_DECL_OVERRIDE&amp;quot;:http://doc.qt.io/qt-5.0/qtcore/qtglobal.html#Q_DECL_OVERRIDE macro after the function declaration, just before the ';' (or the '{' ).

=== Things to avoid ===

* Do not inherit from template/tool classes
** The destructors are not virtual, leading to potential memory leaks
** The symbols are not exported (and mostly inline), leading to interesting symbol clashes.
** Example: Library A has &lt;code&amp;gt;class Q_EXPORT X: public QList&amp;lt;QVariant&amp;gt; {};&lt;/code&amp;gt; and library B has &lt;code&amp;gt;class Q_EXPORT Y: public QList&amp;lt;QVariant&amp;gt; {};&lt;/code&amp;gt;. Suddenly, QList&amp;lt;QVariant&amp;gt;'s symbols are exported from two libraries - /clash/.

* Don't mix const and non-const iterators. This will silently crash on broken compilers.

<code><br /> for (Container::const_iterator it = c.begin(); it != c.end(); +''it) // W R O N G<br /> for (Container::const_iterator it = c.constBegin(); it != c.constEnd();it) // Right<br /></code>
<br />* Q[Core]Application is a singleton class. There can only be one instance at a time. However, that instance can be destroyed and a new one can be created, which is likely in an &lt;nop&amp;gt;ActiveQt or browser plugin. Code like this will easily break:
<br /><code><br /> static QObject '''obj = 0;<br /> if (!obj)<br /> obj = new QObject(QCoreApplication::instance());<br /></code>
<br />If the &lt;code&amp;gt;QCoreApplication&amp;lt;/code&amp;gt; application is destroyed, &lt;code&amp;gt;obj&amp;lt;/code&amp;gt; will be a dangling pointer. Use &lt;code&amp;gt;Q_GLOBAL_STATIC&amp;lt;/code&amp;gt; for static global objects or &lt;code&amp;gt;qAddPostRoutine&amp;lt;/code&amp;gt; to clean up.
<br />''' Avoid the use of anonymous namespaces in favor of the static keyword if possible. A name localized to the compilation unit with &lt;code&amp;gt;static&amp;lt;/code&amp;gt; is guaranteed to have internal linkage. For names declared in anonymous namespaces the C''+ standard unfortunately mandates external linkage. (7.1.1/6, or see various discussions about this on the gcc mailing lists)

=== Binary and Source Compatibility ===

* Definitions:
** Qt 4.0.0 is a major release, Qt 4.1.0 is a minor release, Qt 4.1.1 is a patch release
** Backward binary compatibility: Code linked to an earlier version of the library keeps working
** Forward binary compatibility: Code linked to a newer version of the library works with an older library
** Source code compatibility: Code compiles without modification

* Keep backward binary compatibility + backward source code compatibility in minor releases

* Keep backward and forward binary compatibility + forward and backward source code compatibility in patch releases
** Don't add/remove any public API (e.g. global functions, public/protected/private methods)
** Don't reimplement methods (not even inlines, nor protected/private methods)
** Check [[Binary_Compatibility_Workarounds]|Binary Compatibility Workarounds]] for ways to keep b/c

* Info on binary compatibility: http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++

* When writing a QWidget subclass, always reimplement event(), even if it's empty. This makes sure that the widget can be fixed without breaking binary compatibility.

* All exported functions from Qt must start with either 'q' or 'Q'. Use the &quot;symbols&amp;quot; autotest to find violations.

=== Namespacing ===

* Read [[Qt In Namespace|Qt in Namespace]] and keep in mind that all of Qt except Tests and Webkit is &quot;namespaced&amp;quot; code.

=== Operators ===

* &quot;The decision between member and non-member&amp;quot;:http://stackoverflow.com/questions/4421706/operator-overloading/4421729#4421729

A binary operator that treats both of its arguments equally should not be a member. Because, in addition to the reasons mentioned in the stack overflow answer, the arguments are not equal when the operator is a member.

Example with QLineF which unfortunately has its operator== as a member:

<code>QLineF lineF;<br />QLine lineN;

if (lineF  lineN) // Ok,  lineN is implicitly converted to QLineF
if (lineN  lineF) // Error: QLineF cannot be converted implicitly to QLine, and the LHS is a member so no conversion applies</code>

If the operator== was outside of the class, conversion rules would apply equally for both sides.

== Conventions for public header files ==

Our public header files have to survive the strict settings of some of our users. All installed headers have to follow these rules:

* No C style casts (&lt;code&amp;gt;-Wold-style-cast&amp;lt;/code&amp;gt;)
** Use static_cast, const_cast or reinterpret_cast
** for basic types, use the constructor form: int(a) instead of (int)a
** See chapter &quot;Casting&amp;quot; for more info

* No float comparisons (&lt;code&amp;gt;-Wfloat-equal&amp;lt;/code&amp;gt;)
** Use qFuzzyCompare to compare values with a delta
** Use qIsNull to check whether a float is binary 0, instead of comparing it to 0.0. 

* Don't hide virtual methods in subclasses (&lt;code&amp;gt;-Woverloaded-virtual&amp;lt;/code&amp;gt;)
** If the baseclass &lt;code&amp;gt;A&amp;lt;/code&amp;gt; has a &lt;code&amp;gt;virtual int val()&lt;/code&amp;gt; and subclass &lt;code&amp;gt;B&amp;lt;/code&amp;gt; an overload with the same name, &lt;code&amp;gt;int val(int x)&lt;/code&amp;gt;, &lt;code&amp;gt;A&amp;lt;/code&amp;gt;'s &lt;code&amp;gt;val&amp;lt;/code&amp;gt; function is hidden. Use the &lt;code&amp;gt;using&amp;lt;/code&amp;gt; keyword to make it visible again, and add the following silly workaround for broken compilers:

<code><br /> class B: public A<br /> {<br /> #ifdef Q_NO_USING_KEYWORD<br /> inline int val() { return A::val(); }<br /> #else<br /> using A::val;<br /> #endif<br /> };<br /> </code>

* Don't shadow variables (&lt;code&amp;gt;<s>Wshadow&amp;lt;/code&amp;gt;)<br />'''''' avoid things like &lt;code&amp;gt;this</s>&gt;x = x;&lt;/code&amp;gt;
** don't give variables the same name as functions declared in your class

* Always check whether a preprocessor variable is defined before probing its value (&lt;code&amp;gt;<s>Wundef&amp;lt;/code&amp;gt;)
<br /><code><br /> #if Foo   0  // W R O N G
        #if defined(Foo) &amp;amp;&amp;amp; Foo  0 // Right<br /> #if Foo</s> 0 == 0 // Clever, are we? Use the one above instead, for better readability