Update copyright headers
[qt:qt.git] / doc / src / howtos / qmlbestpractices / qmlbestpractices-coding.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-best-practices-coding.html
30 \ingroup qml-best-practices
31 \contentspage QML Best Practices Guides
32 \previouspage QML Best Practices Guides
33 \startpage QML Best Practices Guides
34 \title QML Best Practices: Coding Conventions
35
36 \brief QML Coding Conventions and Importing Files
37
38 There are many different ways to code using QML. These are a set of
39 guidelines to help your code look better and consistent.
40
41 \section1 Coding Conventions
42
43 The official QML Coding Conventions may be found at
44 \l {QML Coding Conventions}. This is the recommended convention that will be
45 used throughout the QML documentation.
46
47 In addition, Qt's official code style may be found at the \l {Qt Coding Style}.
48
49 \section1 Importing Files into QML
50
51 To import items such as directories, use the "import" keyword, similar to
52 the way the \c {import QtQuick 1.0} statement is used.
53
54 \snippet doc/src/snippets/declarative/imports/best-practices.qml imports
55
56 To facilitate the import of QML components, it is best to begin the QML
57 file with an uppercase character. This way, the user can simply declare the
58 component using the file name as the component name. For example, if a QML
59 component is in a file named \c Button.qml, then the user may import the
60 component by declaring a \c {Button {}}. Note that this method only works if
61 the QML files are in the same directory.
62
63 It is also possible to import QML files which have file names that begin in
64 lower case or files in a different directory by using a \c qmldir file.
65
66 A \c qmldir file tells your QML application which QML components, plugins,
67 or directories to import. The \c qmldir file must reside in an imported
68 directory. By using the \c qmldir file, users may import any QML file and assign any
69 valid QML component name to the component.
70
71 For more information, read the section on
72 \l{qml-loading-components}{Loading a Component}.
73
74 \section1 Commenting Code
75
76 Commenting code allows others to read the source code better. As well, comments
77 allow the programmer to think about his or her code; a confusing comment may
78 mean the code is confusing.
79
80 Similar to JavaScript or C++, there are two ways of commenting QML code:
81 \list
82 \o Single line comments start with \c{//} and finish at the end of the line
83 \o Multiline comments start with \c{/*} and finish with *\/
84 \endlist
85
86 \section1 Group Properties
87
88 Many QML properties are \l{attached-properties}{attached} or
89 \l {qml-grouped-properties}{group} properties. For convenience, you may treat
90 them as another element when dealing with multiple properties belonging to the
91 same group.
92
93 \snippet doc/src/snippets/declarative/bestpractices/group.qml not grouped
94 Treating groups of properties as a block can ease confusion and help relate the
95 properties with other properties.
96 \snippet doc/src/snippets/declarative/bestpractices/group.qml grouped
97 */