|
1 ############################## |
|
2 Coding Conventions |
|
3 ############################## |
|
4 |
|
5 .. index:: |
|
6 module: Coding Conventions |
|
7 |
|
8 .. contents:: |
|
9 |
|
10 Introduction |
|
11 ============ |
|
12 |
|
13 This describes how you should write code for Helium. It covers Ant XML, Java and Python. |
|
14 |
|
15 .. index:: |
|
16 single: General Conventions |
|
17 |
|
18 General conventions |
|
19 =================== |
|
20 |
|
21 * Changing the working directory should be avoided in any language. |
|
22 |
|
23 .. index:: |
|
24 single: Ant Conventions |
|
25 |
|
26 Ant conventions |
|
27 ====================== |
|
28 |
|
29 These conventions are applicable to all Ant XML script files. |
|
30 |
|
31 .. index:: |
|
32 single: XML Indentations |
|
33 |
|
34 XML indentation |
|
35 --------------- |
|
36 |
|
37 * Indents are 4 spaces. Tabs should not be used. |
|
38 * The XML element structure should be consistently indented. |
|
39 |
|
40 .. index:: |
|
41 single: File Names |
|
42 |
|
43 File names |
|
44 ---------- |
|
45 |
|
46 * Ant files intended to be called by a ``bld.bat`` should be named ``build.xml`` (the default name Ant looks for). |
|
47 * All other Ant files should end with "``.ant.xml``". |
|
48 |
|
49 .. index:: |
|
50 single: File Organisation |
|
51 |
|
52 File organisation |
|
53 ----------------- |
|
54 |
|
55 * ``helium.ant.xml`` is the root Ant file under ``/helium`` that includes all the other Ant files. |
|
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``. |
|
57 |
|
58 .. index:: |
|
59 single: Targets |
|
60 |
|
61 Targets |
|
62 ----------- |
|
63 |
|
64 * Target names are a mix of lowercase letters and numbers and the '-' character. |
|
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. |
|
66 * Ant properties are used in preference (where the option exists) to external environment variables (that start with ``env.``). |
|
67 * Targets can be marked as deprecated by adding one optional tag ``<deprecated> value </deprecated>`` in the comment tag top of the target area. |
|
68 * Targets can be marked as private by adding ``Private:`` in the comment tag top of the target area. |
|
69 |
|
70 .. index:: |
|
71 single: Properties |
|
72 |
|
73 .. _properties_label: |
|
74 |
|
75 Properties |
|
76 ---------- |
|
77 |
|
78 * Properties are named using lowercase words separated by the '.' character. |
|
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. |
|
80 * Properties can be marked as deprecated in the data model by adding one optional tag ``<deprecated>``. |
|
81 |
|
82 .. csv-table:: Property naming conventions |
|
83 :header: "Rule", "Description" |
|
84 |
|
85 "File paths", "Property name should end with ``.file``" |
|
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." |
|
87 "Value list", "Property name should end with ``.list``." |
|
88 |
|
89 Ant tasks |
|
90 --------- |
|
91 |
|
92 There are two preferred ways to implement an Ant task: |
|
93 |
|
94 * A pure Java Task subclass. |
|
95 * A ``<scriptdef>`` task using Jep. |
|
96 |
|
97 In general these guidelines should be noted: |
|
98 |
|
99 * Use short, descriptive task names that fit with the Ant naming style. All custom tasks should be under the ``hlm:`` namespace. |
|
100 * Avoid referencing property values directly inside the task implementation. Data values should typically be passed as attributes. |
|
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. |
|
102 |
|
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. |
|
104 |
|
105 Scripts |
|
106 ------- |
|
107 |
|
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: |
|
109 |
|
110 * A ``<script>`` task using Jep. |
|
111 * A ``<hlm:python>`` task using embedded Python code. This typically does not allow much interaction with the Ant process. |
|
112 |
|
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:: |
|
114 |
|
115 <hlm:python> |
|
116 import mycode |
|
117 mycode.dostuff(r'${prop.1}') |
|
118 </hlm:python> |
|
119 |
|
120 <script language="jep"> |
|
121 import mycode |
|
122 value = mycode.dostuff(project.getProperty('prop.1')) |
|
123 project.setProperty('xyz', value) |
|
124 </script> |
|
125 |
|
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. |
|
127 |
|
128 .. index:: |
|
129 single: Java conventions |
|
130 |
|
131 Java conventions |
|
132 ================ |
|
133 |
|
134 .. index:: |
|
135 single: Ant Task Documentions |
|
136 |
|
137 Ant task documentation |
|
138 ---------------------- |
|
139 |
|
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:: |
|
141 |
|
142 /** |
|
143 * Code Sample for Ant Task class Comments |
|
144 * @ant.task name="copy" category="filesystem" |
|
145 * @ant.task ignored="true" |
|
146 */ |
|
147 public class Copy |
|
148 |
|
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:: |
|
150 |
|
151 /** |
|
152 * Code Sample for Ant Task property Comments |
|
153 * @ant.required |
|
154 * Default is false. |
|
155 */ |
|
156 public void setOverwrite(boolean overwrite){ |
|
157 this.forceOverwrite = overwrite; |
|
158 } |
|
159 |
|
160 All custom tasks should be commented in this way. |
|
161 |
|
162 .. index:: |
|
163 single: File Execution |
|
164 |
|
165 File execution |
|
166 ============== |
|
167 |
|
168 File execution should not depend on the extension of the file. The appropriate executable should be used to run the script, e.g:: |
|
169 |
|
170 python foo.py |
|
171 |
|
172 not:: |
|
173 |
|
174 foo.py |
|
175 |
|
176 |
|
177 .. index:: |
|
178 single: Documentation conventions |
|
179 |
|
180 Documentation conventions |
|
181 ========================= |
|
182 |
|
183 Standalone documents are written in reStructuredText_ format. |
|
184 |
|
185 .. _reStructuredText : http://docutils.sourceforge.net/rst.html |
|
186 |
|
187 |
|
188 .. index:: |
|
189 single: Python conventions |
|
190 |
|
191 Python conventions |
|
192 ========================= |
|
193 |
|
194 Specific conventions |
|
195 -------------------- |
|
196 |
|
197 Python Code Indentation |
|
198 ``````````````````````` |
|
199 |
|
200 * Indents are 4 spaces. Tabs should not be used. |
|
201 |
|
202 |
|
203 Documentation |
|
204 ````````````` |
|
205 |
|
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. |
|
207 |
|
208 .. _`PEP 257 - Docstring Conventions` : http://www.python.org/dev/peps/pep-0257/ |
|
209 .. _Epydoc : http://epydoc.sourceforge.net/ |
|
210 |
|
211 |
|
212 Unit testing |
|
213 ```````````` |
|
214 |
|
215 * Unit tests are written for each Python module. |
|
216 * They should follow the Nose_ testing framework conventions. |
|
217 * The test suite is run by calling ``hlm py-unittest``. |
|
218 |
|
219 .. _Nose : http://somethingaboutorange.com/mrl/projects/nose/ |
|
220 |
|
221 |
|
222 Lint |
|
223 ```` |
|
224 |
|
225 * Always check your code with pylint_ before checking it in. |
|
226 * Aim for pylint_ score >= 8. |
|
227 |
|
228 .. _pylint: http://www.logilab.org/857 |
|
229 |
|
230 |
|
231 Reference coding standards |
|
232 -------------------------- |
|
233 |
|
234 These reference standards are used for all conventions not covered above. |
|
235 |
|
236 * `PEP 8 - Style Guide for Python Code`_. |
|
237 * `Twisted Coding Standard`_ (but with a grain of salt): |
|
238 |
|
239 .. _`PEP 8 - Style Guide for Python Code` : http://www.python.org/dev/peps/pep-0008/ |
|
240 .. _`Twisted Coding Standard` : http://twistedmatrix.com/trac/browser/trunk/doc/development/policy/coding-standard.xhtml?format=raw |
|
241 |
|
242 |
|
243 .. index:: |
|
244 single: Quality Checklist |
|
245 |
|
246 Quality checklist |
|
247 ================= |
|
248 |
|
249 '''Python''' |
|
250 |
|
251 * All modules have a single description line in the module comment. |
|
252 |
|
253 .. index:: |
|
254 single: Bad Word Scanner configuration |
|
255 |
|
256 Bad Word Scanner configuration |
|
257 ============================== |
|
258 |
|
259 This section will probably only ever be used by a helium contributor: |
|
260 |
|
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 |
|
262 in a .cvs file and scan the directory of the source code. Bad words include Nokia product names, competitors product names etc. |
|
263 |
|
264 Run the following command :: |
|
265 |
|
266 hlm check-bad-words |