source: trunk/doc/src/declarative/codingconventions.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 3.9 KB
RevLine 
[844]1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29\page qml-coding-conventions.html
30\title QML Coding Conventions
31
32This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.
33
34This page assumes that you are already familiar with the QML language.
35If 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
40Through 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
53For better readability, we separate these different parts with an empty line.
54
55
56For 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
63If using multiple properties from a group of properties,
64we use the \e {group notation} rather than the \e {dot notation} to improve readability.
65
66For example, this:
67
68\snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 0
69
70can be written like this:
71
72\snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 1
73
74
75\section1 Private Properties
76
77QML and JavaScript do not enforce private properties like C++. There is a need
78to hide these private properties, for example, when the properties are part of
79the implementation. As a convention, private properties begin with two
80\e underscore characters. For example, \c __area, is a property that is
81accessible but is not meant for public use. Note that QML and JavaScript will
82grant the user access to these properties.
83
84\snippet doc/src/snippets/declarative/codingconventions/private.qml 0
85
86
87\section1 Lists
88
89If a list contains only one element, we generally omit the square brackets.
90
91For example, it is very common for a component to only have one state.
92
93In this case, instead of:
94
95\snippet doc/src/snippets/declarative/codingconventions/lists.qml 0
96
97we will write this:
98
99\snippet doc/src/snippets/declarative/codingconventions/lists.qml 1
100
101
102\section1 JavaScript Code
103
104If the script is a single expression, we recommend writing it inline:
105
106\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 0
107
108If the script is only a couple of lines long, we generally use a block: