doc/src/declarative/codingconventions.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  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 qt-info@nokia.com.
  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. 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.
  83
  84 \snippet doc/src/snippets/declarative/codingconventions/private.qml 0
  85
  86
  87 \section1 Lists
  88
  89 If a list contains only one element, we generally omit the square brackets.
  90
  91 For example, it is very common for a component to only have one state.
  92
  93 In this case, instead of:
  94
  95 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 0
  96
  97 we will write this:
  98
  99 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 1
 100
 101
 102 \section1 JavaScript Code
 103
 104 If the script is a single expression, we recommend writing it inline:
 105
 106 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 0
 107
 108 If the script is only a couple of lines long, we generally use a block:
 109
 110 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 1
 111
 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:
 113
 114 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2
 115
 116 For long scripts, we will put the functions in their own JavaScript file and import it like this:
 117
 118 \snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0
 119
 120 */
 121
 122
 123
 124
 125
 126
 127
 128
 129