doc/src/declarative/codingconventions.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   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
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qml-coding-conventions.html
  30 \inqmlmodule QtQuick 2
  31 \title QML Coding Conventions
  32
  33 This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.
  34
  35 This page assumes that you are already familiar with the QML language.
  36 If you need an introduction to the language, please read \l {Introduction to the QML language}{the QML introduction} first.
  37
  38
  39 \section1 QML Objects
  40
  41 Through our documentation and examples, QML objects are always structured in the following order:
  42
  43 \list
  44 \o id
  45 \o property declarations
  46 \o signal declarations
  47 \o JavaScript functions
  48 \o object properties
  49 \o child objects
  50 \o states
  51 \o transitions
  52 \endlist
  53
  54 For better readability, we separate these different parts with an empty line.
  55
  56
  57 For example, a hypothetical \i photo QML object would look like this:
  58
  59 \snippet doc/src/snippets/declarative/codingconventions/photo.qml 0
  60
  61
  62 \section1 Grouped Properties
  63
  64 If using multiple properties from a group of properties,
  65 we use the \i {group notation} rather than the \i {dot notation} to improve readability.
  66
  67 For example, this:
  68
  69 \snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 0
  70
  71 can be written like this:
  72
  73 \snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 1
  74
  75
  76 \section1 Private Properties
  77
  78 QML and JavaScript do not enforce private properties like C++. There is a need
  79 to hide these private properties, for example, when the properties are part of
  80 the implementation. As a convention, private properties begin with two
  81 \i underscore characters. For example, \c __area, is a property that is
  82 accessible but is not meant for public use. Note that QML and JavaScript will
  83 grant the user access to these properties.
  84
  85 \snippet doc/src/snippets/declarative/codingconventions/private.qml 0
  86
  87
  88 \section1 Lists
  89
  90 If a list contains only one element, we generally omit the square brackets.
  91
  92 For example, it is very common for a component to only have one state.
  93
  94 In this case, instead of:
  95
  96 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 0
  97
  98 we will write this:
  99
 100 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 1
 101
 102
 103 \section1 JavaScript Code
 104
 105 If the script is a single expression, we recommend writing it inline:
 106
 107 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 0
 108
 109 If the script is only a couple of lines long, we generally use a block:
 110
 111 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 1
 112
 113 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
 115 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2
 116
 117 For long scripts, we will put the functions in their own JavaScript file and import it like this:
 118
 119 \snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0
 120
 121 */
 122
 123
 124
 125
 126
 127
 128
 129
 130