Directory Layout

Each git repository should have an examples/ directory that contains subdirectories matching the Qt modules or tools in the repository.

For instance qtdeclarative.git has:

examples.pro
examples/qml
examples/quick
...

Installers merge the example directories from different modules, so the subdirectories must be unique across the repositories.

Every subdirectoy may, in turn, group examples into a directory hierarchy.

The source directory of an example should be self-contained. That is, it should still build when copied out of the Qt source tree.

Each example must be documented. This is usually done in a doc/ subdirectory of the example.

Launching

An example should launch from Qt Creator without any further actions necessary. In the few cases where this is not possible, the example should prominently state the steps necessary to try out the example.

File Naming

The example's .pro file should have the same name as the directory.

If the example has a C++ entry point, it should be in the file main.cpp. Try to keep this as simple as possible: Most users have understood that main() is usually boring and seldom take time to read it.

In general, each C++ class should be defined in its own header file and implemented in its own .cpp file. Try to avoid defining more than one class per header file unless you have lots of small classes (for example an undo/redo framework, with one class per type of action). Local helper classes can also be introduced in a .cpp file.

For Qt Quick examples, the .qml file that contains the QML entry point and a .qmlproject file should be named the same as the directory.

Coding Style

Examples should follow the general Qt coding style, with some exceptions:

C++ includes should use the camel-case class name notation, for example:

#include <QCoreApplication>

not:

#include <QtCore/QCoreApplication>
#include <qcoreapplication.h>

In C++, signals and slots keywords are preferred over their Q_SIGNAL, Q_SLOT variants.

Finally, example code should wrap at 80 characters, because it's often quoted in the documentation.

Comments

Keep comments in source code minimal. Documentation and explanations belong in the example's exposition.

Conditional Compilation

Use the preprocessor exclusively to protect against multiple inclusion of header files. In particular, do not use the Qt feature system to disable parts of an example, because the individual features are currently not part of the public API. Instead, the build system should skip examples that do not have required dependencies.

Application Settings

Examples and demos should store their custom settings in a common QtExamples scope, so that the settings do not litter the user settings too much. This is usually done by calling:

QCoreApplication::setOrganizationName("QtExamples");

in main.cpp.

Licenses and Third-Party Assets

Examples should be made available under the Commercial/BSD 3 clause license (see header.BSD).

Code or assets (including images) from third-party sources need to be explicitly documented as such. See QUIP-4 for the details.