1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qml-coding-conventions.html
30 \title QML Coding Conventions
32 This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.
34 This page assumes that you are already familiar with the QML language.
35 If you need an introduction to the language, please read \l {Introduction to the QML language}{the QML introduction} first.
40 Through our documentation and examples, QML objects are always structured in the following order:
44 \o property declarations
45 \o signal declarations
46 \o JavaScript functions
53 For better readability, we separate these different parts with an empty line.
56 For example, a hypothetical \e photo QML object would look like this:
58 \snippet doc/src/snippets/declarative/codingconventions/photo.qml 0
61 \section1 Grouped Properties
63 If using multiple properties from a group of properties,
64 we use the \e {group notation} rather than the \e {dot notation} to improve readability.
68 \snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 0
70 can be written like this:
72 \snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 1
75 \section1 Private Properties
77 QML and JavaScript do not enforce private properties like C++. There is a need
78 to hide these private properties, for example, when the properties are part of
79 the implementation. As a convention, private properties begin with two
80 \e underscore characters. For example, \c __area, is a property that is
81 accessible but is not meant for public use. Note that QML and JavaScript will
82 grant the user access to these properties.
84 \snippet doc/src/snippets/declarative/codingconventions/private.qml 0
89 If a list contains only one element, we generally omit the square brackets.
91 For example, it is very common for a component to only have one state.
93 In this case, instead of:
95 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 0
99 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 1
102 \section1 JavaScript Code
104 If the script is a single expression, we recommend writing it inline:
106 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 0
108 If the script is only a couple of lines long, we generally use a block:
110 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 1
112 If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this:
114 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2
116 For long scripts, we will put the functions in their own JavaScript file and import it like this:
118 \snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0