buildframework/helium/doc/src/coding_conventions.rst
author jchatten
Mon, 07 Dec 2009 15:19:38 +0000
branchfix
changeset 41 8271ebf1309f
parent 1 be27ed110b50
permissions -rw-r--r--
Corrected test script.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     1
##############################
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     2
Coding Conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     3
##############################
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     4
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     5
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     6
  module: Coding Conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     7
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     8
.. contents::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
     9
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    10
Introduction
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    11
============
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    12
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    13
This describes how you should write code for Helium. It covers Ant XML, Java and Python.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    14
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    15
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    16
  single: General Conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    17
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    18
General conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    19
===================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    20
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    21
* Changing the working directory should be avoided in any language.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    22
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    23
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    24
  single: Ant Conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    25
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    26
Ant conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    27
======================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    28
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    29
These conventions are applicable to all Ant XML script files.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    30
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    31
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    32
  single: XML Indentations
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    33
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    34
XML indentation
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    35
---------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    36
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    37
* Indents are 4 spaces. Tabs should not be used.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    38
* The XML element structure should be consistently indented.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    39
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    40
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    41
  single: File Names
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    42
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    43
File names
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    44
----------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    45
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    46
* Ant files intended to be called by a ``bld.bat`` should be named ``build.xml`` (the default name Ant looks for).
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    47
* All other Ant files should end with "``.ant.xml``".
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    48
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    49
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    50
  single: File Organisation
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    51
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    52
File organisation
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    53
-----------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    54
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    55
* ``helium.ant.xml`` is the root Ant file under ``/helium`` that includes all the other Ant files.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    56
* ``helium.ant.xml`` should only include top-level build stage Ant files, e.g. ``preparation.ant.xml``. Within each build stage directory, further Ant files should be included by that build stage file. This reduces frequent edits to ``helium.ant.xml``.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    57
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    58
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    59
  single: Targets
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    60
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    61
Targets
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    62
-----------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    63
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    64
* Target names are a mix of lowercase letters and numbers and the '-' character.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    65
* Configuration files needed as input to external scripts/tools are not defined as arguments using any kind of hardcoded path (absolute or relative). Rather an Ant property should define the path to the file and that property value is used as the argument in the call to the tool.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    66
* Ant properties are used in preference (where the option exists) to external environment variables (that start with ``env.``).
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    67
* Targets can be marked as deprecated by adding one optional tag ``<deprecated> value </deprecated>`` in the comment tag top of the target area.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    68
* Targets can be marked as private by adding ``Private:`` in the comment tag top of the target area.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    69
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    70
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    71
  single: Properties
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    72
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    73
.. _properties_label:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    74
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    75
Properties
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    76
----------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    77
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    78
* Properties are named using lowercase words separated by the '.' character.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    79
* Values should not have any dependencies on the location of the ``helium`` project. Based on the ``HELIUM_HOME`` setting, the project could be anywhere, so paths should not assume it to be relative to any other location.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    80
* Properties can be marked as deprecated in the data model by adding one optional tag ``<deprecated>``.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    81
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    82
.. csv-table:: Property naming conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    83
   :header: "Rule", "Description"
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    84
   
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    85
   "File paths", "Property name should end with ``.file``"
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    86
   "Directory paths", "Property name should end with ``.dir``. The ``location`` attribute is recommended over ``value``. No trailing slashes are required. Paths should use other properties such as ``build.drive`` to be flexible. Forward slashes should be used, unless backslashes are specifically needed."
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    87
   "Value list", "Property name should end with ``.list``."
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    88
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    89
Ant tasks
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    90
---------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    91
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    92
There are two preferred ways to implement an Ant task:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    93
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    94
* A pure Java Task subclass.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    95
* A ``<scriptdef>`` task using Jep.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    96
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    97
In general these guidelines should be noted:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    98
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    99
* Use short, descriptive task names that fit with the Ant naming style. All custom tasks should be under the ``hlm:`` namespace.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   100
* Avoid referencing property values directly inside the task implementation. Data values should typically be passed as attributes.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   101
* Do not put Jep code inside a .py file. Pylint cannot handle the Java-related syntax. Rather use the embedded scriptdef code to handle the Jep-specific parts and use pure Python libraries where necessary. Use a ``.jep`` file extension if moving the entire scriptdef content out to a separate file.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   102
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   103
Implement using tasks when the functionality may be used in more than one place or it will help the design and maintenance to provide a well-defined interface for that function.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   104
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   105
Scripts
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   106
-------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   107
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   108
A script allows more flexible code than is provided by the standard tasks while not being as formalized as a new custom task. There are two preferred ways to implement embedded scripts:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   109
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   110
* A ``<script>`` task using Jep.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   111
* A ``<hlm:python>`` task using embedded Python code. This typically does not allow much interaction with the Ant process.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   112
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   113
Here properties can be accessed directly but it is good practice to only reference them in the embedded code. If the functionality is significant create separate Python libraries as needed and call them from the embedded script, e.g::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   114
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   115
    <hlm:python>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   116
    import mycode
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   117
    mycode.dostuff(r'${prop.1}')
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   118
    </hlm:python>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   119
    
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   120
    <script language="jep">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   121
    import mycode
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   122
    value = mycode.dostuff(project.getProperty('prop.1'))
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   123
    project.setProperty('xyz', value)
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   124
    </script>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   125
    
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   126
Use a script when prototyping or a more specialized operation is needed in only one place. Embedded scripts should generally be kept as short as possible.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   127
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   128
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   129
  single: Java conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   130
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   131
Java conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   132
================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   133
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   134
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   135
  single: Ant Task Documentions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   136
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   137
Ant task documentation
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   138
----------------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   139
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   140
* Javadoc comment of a Ant task class should include the Ant-specific tag ``@ant.task``. It accepts three "attributes": ``name``, ``category`` and ``ignored``. When ``ignored=true``, the class will not be included in the documentation. For example::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   141
    
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   142
    /**
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   143
     * Code Sample for Ant Task class Comments
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   144
     * @ant.task name="copy" category="filesystem"
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   145
     * @ant.task ignored="true"
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   146
     */
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   147
    public class Copy
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   148
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   149
* The task properties documentation is extracted from the property getter/setter methods. The tags are ``@ant.required`` and ``@ant.not-required`` which indicate if the property is required or not required. For example::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   150
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   151
    /**
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   152
     * Code Sample for Ant Task property Comments
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   153
     * @ant.required 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   154
     * Default is false.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   155
     */
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   156
    public void setOverwrite(boolean overwrite){ 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   157
        this.forceOverwrite = overwrite;
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   158
    }
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   159
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   160
All custom tasks should be commented in this way.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   161
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   162
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   163
  single: File Execution
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   164
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   165
File execution
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   166
==============
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   167
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   168
File execution should not depend on the extension of the file. The appropriate executable should be used to run the script, e.g::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   169
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   170
    python foo.py
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   171
    
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   172
not::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   173
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   174
    foo.py
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   175
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   176
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   177
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   178
  single: Documentation conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   179
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   180
Documentation conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   181
=========================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   182
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   183
Standalone documents are written in reStructuredText_ format.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   184
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   185
.. _reStructuredText : http://docutils.sourceforge.net/rst.html
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   186
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   187
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   188
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   189
  single: Python conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   190
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   191
Python conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   192
=========================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   193
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   194
Specific conventions
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   195
--------------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   196
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   197
Python Code Indentation
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   198
```````````````````````
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   199
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   200
* Indents are 4 spaces. Tabs should not be used.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   201
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   202
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   203
Documentation
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   204
`````````````
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   205
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   206
* Docstrings are written in reStructuredText_ format, according to `PEP 257 - Docstring Conventions`_. Documentation is extracted using Epydoc_, so the reStructuredText tags that Epydoc recognises are used.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   207
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   208
.. _`PEP 257 - Docstring Conventions` : http://www.python.org/dev/peps/pep-0257/
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   209
.. _Epydoc : http://epydoc.sourceforge.net/
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   210
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   211
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   212
Unit testing
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   213
````````````
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   214
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   215
* Unit tests are written for each Python module.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   216
* They should follow the Nose_ testing framework conventions.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   217
* The test suite is run by calling ``hlm py-unittest``.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   218
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   219
.. _Nose : http://somethingaboutorange.com/mrl/projects/nose/
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   220
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   221
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   222
Lint 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   223
````
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   224
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   225
* Always check your code with pylint_ before checking it in.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   226
* Aim for pylint_ score >= 8.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   227
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   228
.. _pylint: http://www.logilab.org/857
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   229
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   230
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   231
Reference coding standards
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   232
--------------------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   233
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   234
These reference standards are used for all conventions not covered above.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   235
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   236
* `PEP 8 - Style Guide for Python Code`_.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   237
* `Twisted Coding Standard`_ (but with a grain of salt):
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   238
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   239
.. _`PEP 8 - Style Guide for Python Code` : http://www.python.org/dev/peps/pep-0008/
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   240
.. _`Twisted Coding Standard` : http://twistedmatrix.com/trac/browser/trunk/doc/development/policy/coding-standard.xhtml?format=raw
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   241
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   242
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   243
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   244
  single: Quality Checklist
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   245
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   246
Quality checklist
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   247
=================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   248
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   249
'''Python'''
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   250
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   251
* All modules have a single description line in the module comment.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   252
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   253
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   254
  single: Bad Word Scanner configuration
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   255
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   256
Bad Word Scanner configuration
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   257
==============================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   258
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   259
This section will probably only ever be used by a helium contributor:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   260
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   261
Bad word scanner scans the helium code for the words that should not be in the helium source code. You need to include the bad words
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   262
in a .cvs file and scan the directory of the source code. Bad words include Nokia product names, competitors product names etc.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   263
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   264
Run the following command ::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   265
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   266
    hlm check-bad-words