|
33
|
1 Developer's guide
|
|
|
2 #################
|
|
|
3
|
|
|
4 :Author: Ben Finney <ben+python@benfinney.id.au>
|
|
|
5 :Updated: 2014-11-28
|
|
|
6
|
|
|
7
|
|
|
8 Project layout
|
|
|
9 ==============
|
|
|
10
|
|
|
11 ::
|
|
|
12
|
|
|
13 ./ Top level of source tree
|
|
|
14 doc/ Project documentation
|
|
|
15 bin/ Executable programs
|
|
|
16 daemon/ Main ‘daemon’ library
|
|
|
17 test/ Unit tests
|
|
|
18
|
|
|
19
|
|
|
20 Code style
|
|
|
21 ==========
|
|
|
22
|
|
|
23 Python
|
|
|
24 ------
|
|
|
25
|
|
|
26 All Python code should conform to the guidelines in PEP8_. In
|
|
|
27 particular:
|
|
|
28
|
|
|
29 * Indent each level using 4 spaces (``U+0020 SPACE``), and no TABs
|
|
|
30 (``U+0008 CHARACTER TABULATION``).
|
|
|
31
|
|
|
32 * Name modules in lower case, ``multiplewordslikethis``.
|
|
|
33
|
|
|
34 * Name classes in title case, ``MultipleWordsLikeThis``.
|
|
|
35
|
|
|
36 * Name functions, instances and other variables in lower case,
|
|
|
37 ``multiple_words_like_this``.
|
|
|
38
|
|
|
39 * Every module, class, and function has a Python doc string explaining
|
|
|
40 its purpose and API.
|
|
|
41
|
|
|
42 *Exception*: Functions whose purpose and API are mandated by Python
|
|
|
43 itself (dunder-named methods) do not need a doc string.
|
|
|
44
|
|
|
45 * Doc strings are written as triple-quoted strings.
|
|
|
46
|
|
|
47 * The text of the doc string is marked up with reStructuredText.
|
|
|
48
|
|
|
49 * The first line is a one-line synopsis of the object. This summary
|
|
|
50 line appears on the same line as the opening triple-quote,
|
|
|
51 separated by a single space.
|
|
|
52
|
|
|
53 * Further lines, if needed, are separated from the first by one
|
|
|
54 blank line.
|
|
|
55
|
|
|
56 * The synopsis is separated by one space from the opening
|
|
|
57 triple-quote; this causes it to appear four columns past the
|
|
|
58 beginning of the line. All subsequent lines are indented at least
|
|
|
59 four columns also.
|
|
|
60
|
|
|
61 * The synopsis is followed by a reStructuredText field list. The
|
|
|
62 field names are: “param foo” for each parameter (where “foo” is
|
|
|
63 the parameter name), and “return” for the return value. The field
|
|
|
64 values describe the purpose of each.
|
|
|
65
|
|
|
66 * The closing triple-quote appears on a separate line.
|
|
|
67
|
|
|
68 Example::
|
|
|
69
|
|
|
70 def frobnicate(spam, algorithm="dv"):
|
|
|
71 """ Perform frobnication on ``spam``.
|
|
|
72
|
|
|
73 :param spam: A travortionate (as a sequence of strings).
|
|
|
74 :param algorithm: The name of the algorithm to use for
|
|
|
75 frobnicating the travortionate.
|
|
|
76 :return: The frobnicated travortionate, if it is
|
|
|
77 non-empty; otherwise None.
|
|
|
78
|
|
|
79 The frobnication is done by the Dietzel-Venkman algorithm,
|
|
|
80 and optimises for the case where ``spam`` is freebled and
|
|
|
81 agglutinative.
|
|
|
82
|
|
|
83 """
|
|
|
84 spagnify(spam)
|
|
|
85 # …
|
|
|
86
|
|
|
87 * All ``import`` statements appear at the top of the module.
|
|
|
88
|
|
|
89 * Each ``import`` statement imports a single module, or multiple names
|
|
|
90 from a single module.
|
|
|
91
|
|
|
92 Example::
|
|
|
93
|
|
|
94 import sys
|
|
|
95 import os
|
|
|
96 from spam import foo, bar, baz
|
|
|
97
|
|
|
98 .. _PEP8: http://www.python.org/dev/peps/pep-0008/
|
|
|
99
|
|
|
100 Additional style guidelines:
|
|
|
101
|
|
|
102 * All text files (including program code) are encoded in UTF-8.
|
|
|
103
|
|
|
104 * A page break (``U+000C FORM FEED``) whitespace character is used
|
|
|
105 within a module to break up semantically separate areas of the
|
|
|
106 module.
|
|
|
107
|
|
|
108 * Editor hints for Emacs and Vim appear in a comment block at the
|
|
|
109 file's end::
|
|
|
110
|
|
|
111
|
|
|
112 # Local variables:
|
|
|
113 # coding: utf-8
|
|
|
114 # mode: python
|
|
|
115 # End:
|
|
|
116 # vim: fileencoding=utf-8 filetype=python :
|
|
|
117
|
|
|
118
|
|
|
119 Unit tests
|
|
|
120 ==========
|
|
|
121
|
|
|
122 All code should aim for 100% coverage by unit tests. New code, or
|
|
|
123 changes to existing code, will only be considered for inclusion in the
|
|
|
124 development tree when accompanied by corresponding additions or
|
|
|
125 changes to the unit tests.
|
|
|
126
|
|
|
127 Test-driven development
|
|
|
128 -----------------------
|
|
|
129
|
|
|
130 Where possible, practice test-driven development to implement program
|
|
|
131 code.
|
|
|
132
|
|
|
133 * During a development session, maintain a separate window or terminal
|
|
|
134 with the unit test suite for the project running continuously, or
|
|
|
135 automatically every few seconds.
|
|
|
136
|
|
|
137 * Any time a test is failing, the only valid change is to make all
|
|
|
138 tests pass.
|
|
|
139
|
|
|
140 * Develop new interface features (changes to the program unit's
|
|
|
141 behaviour) only when all current tests pass.
|
|
|
142
|
|
|
143 * Refactor as needed, but only when all tests pass.
|
|
|
144
|
|
|
145 * Refactoring is any change to the code which does not alter its
|
|
|
146 interface or expected behaviour, such as performance
|
|
|
147 optimisations, readability improvements, modularisation
|
|
|
148 improvements etc.
|
|
|
149
|
|
|
150 * Develop new or changed program behaviour by:
|
|
|
151
|
|
|
152 * *First* write a single, specific test case for that new behaviour,
|
|
|
153 then watch the test fail in the absence of the desired behaviour.
|
|
|
154
|
|
|
155 * Implement the minimum necessary change to satisfy the failing
|
|
|
156 test. Continue until all tests pass again, then stop making
|
|
|
157 functional changes.
|
|
|
158
|
|
|
159 * Once all tests (including the new test) pass, consider refactoring
|
|
|
160 the code and the tests immediately, then ensure all the tests pass
|
|
|
161 again after any changes.
|
|
|
162
|
|
|
163 * Iterate for each incremental change in interface or behaviour.
|
|
|
164
|
|
|
165 Test-driven development is not absolutely necessary, but is the
|
|
|
166 simplest, most direct way to generate the kind of program changes
|
|
|
167 accompanied by unit tests that are necessary for inclusion in the
|
|
|
168 project.
|
|
|
169
|
|
|
170
|
|
|
171 ..
|
|
|
172 Local variables:
|
|
|
173 coding: utf-8
|
|
|
174 mode: rst
|
|
|
175 time-stamp-format: "%:y-%02m-%02d"
|
|
|
176 time-stamp-start: "^:Updated:[ ]+"
|
|
|
177 time-stamp-end: "$"
|
|
|
178 time-stamp-line-limit: 20
|
|
|
179 End:
|
|
|
180 vim: fileencoding=utf-8 filetype=rst :
|
