Update copyright headers
[qt:qt.git] / doc / src / declarative / codingconventions.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29 \page qml-coding-conventions.html
30 \title QML Coding Conventions
31
32 This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.
33
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.
36
37
38 \section1 QML Objects
39
40 Through our documentation and examples, QML objects are always structured in the following order:
41
42 \list
43 \o id
44 \o property declarations
45 \o signal declarations
46 \o JavaScript functions
47 \o object properties
48 \o child objects
49 \o states
50 \o transitions
51 \endlist
52
53 For better readability, we separate these different parts with an empty line.
54
55
56 For example, a hypothetical \e photo QML object would look like this:
57
58 \snippet doc/src/snippets/declarative/codingconventions/photo.qml 0
59
60
61 \section1 Grouped Properties
62
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.
65
66 For example, this:
67
68 \snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 0
69
70 can be written like this:
71
72 \snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 1
73
74
75 \section1 Private Properties
76
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. To effectively gain private properties in a QML Item, the
80 convention is to add a QtObject{} child to contain the properties. This shields them from being accessed outside the file in QML and JavaScript. As it involves the creation of another object, it is more expensive than just creating a property. To minimize the performance cost, try to group all private properties in one file into the same QtObject.
81
82 \snippet doc/src/snippets/declarative/codingconventions/private.qml 0
83
84
85 \section1 Lists
86
87 If a list contains only one element, we generally omit the square brackets.
88
89 For example, it is very common for a component to only have one state.
90
91 In this case, instead of:
92
93 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 0
94
95 we will write this:
96
97 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 1
98
99
100 \section1 JavaScript Code
101
102 If the script is a single expression, we recommend writing it inline:
103
104 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 0
105
106 If the script is only a couple of lines long, we generally use a block:
107
108 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 1
109
110 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:
111
112 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2
113
114 For long scripts, we will put the functions in their own JavaScript file and import it like this:
115
116 \snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0
117
118 */
119
120
121
122
123
124
125
126
127