← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/code-style.txt

Merge cleanup into first-try

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/code-style.txt
 
1
***********************
 
2
Bazaar Code Style Guide
 
3
***********************
 
4
 
 
5
Code layout
 
6
===========
 
7
 
 
8
Please write PEP-8__ compliant code.
 
9
 
 
10
__ http://www.python.org/peps/pep-0008.html
 
11
 
 
12
One often-missed requirement is that the first line of docstrings
 
13
should be a self-contained one-sentence summary.
 
14
 
 
15
We use 4 space indents for blocks, and never use tab characters.  (In vim,
 
16
``set expandtab``.)
 
17
 
 
18
Trailing white space should be avoided, but is allowed.
 
19
You should however not make lots of unrelated white space changes.
 
20
 
 
21
Unix style newlines (LF) are used.
 
22
 
 
23
Each file must have a newline at the end of it.
 
24
 
 
25
Lines should be no more than 79 characters if at all possible.
 
26
Lines that continue a long statement may be indented in either of
 
27
two ways:
 
28
 
 
29
within the parenthesis or other character that opens the block, e.g.::
 
30
 
 
31
    my_long_method(arg1,
 
32
                   arg2,
 
33
                   arg3)
 
34
 
 
35
or indented by four spaces::
 
36
 
 
37
    my_long_method(arg1,
 
38
        arg2,
 
39
        arg3)
 
40
 
 
41
The first is considered clearer by some people; however it can be a bit
 
42
harder to maintain (e.g. when the method name changes), and it does not
 
43
work well if the relevant parenthesis is already far to the right.  Avoid
 
44
this::
 
45
 
 
46
     self.legbone.kneebone.shinbone.toebone.shake_it(one,
 
47
                                                     two,
 
48
                                                     three)
 
49
 
 
50
but rather ::
 
51
 
 
52
     self.legbone.kneebone.shinbone.toebone.shake_it(one,
 
53
         two,
 
54
         three)
 
55
 
 
56
or ::
 
57
 
 
58
     self.legbone.kneebone.shinbone.toebone.shake_it(
 
59
         one, two, three)
 
60
 
 
61
For long lists, we like to add a trailing comma and put the closing
 
62
character on the following line.  This makes it easier to add new items in
 
63
future::
 
64
 
 
65
    from bzrlib.goo import (
 
66
        jam,
 
67
        jelly,
 
68
        marmalade,
 
69
        )
 
70
 
 
71
There should be spaces between function parameters, but not between the
 
72
keyword name and the value::
 
73
 
 
74
    call(1, 3, cheese=quark)
 
75
 
 
76
 
 
77
Python versions
 
78
===============
 
79
 
 
80
Bazaar supports Python from 2.4 through 2.6, and in the future we want to
 
81
support Python 3.0.  Avoid using language features added in 2.5 or 2.6, or
 
82
features deprecated in Python 3.0.  (You can check v3 compatibility using
 
83
the ``-3`` option of Python2.6.)
 
84
 
 
85
Specifically:
 
86
 
 
87
 * Don't use the ``with`` statement.
 
88
 
 
89
 * Don't ``from . import``.
 
90
 
 
91
 * Don't use ``try/except/finally``, which is not supported in Python2.4,
 
92
   use separate nested ``try/except`` and ``try/finally`` blocks.
 
93
 
 
94
 
 
95
hasattr and getattr
 
96
===================
 
97
 
 
98
``hasattr`` should not be used because it swallows exceptions including
 
99
``KeyboardInterrupt``.  Instead, say something like ::
 
100
 
 
101
  if getattr(thing, 'name', None) is None
 
102
 
 
103
 
 
104
Module Imports
 
105
==============
 
106
 
 
107
* Imports should be done at the top-level of the file, unless there is
 
108
  a strong reason to have them lazily loaded when a particular
 
109
  function runs.  Import statements have a cost, so try to make sure
 
110
  they don't run inside hot functions.
 
111
 
 
112
* Module names should always be given fully-qualified,
 
113
  i.e. ``bzrlib.hashcache`` not just ``hashcache``.
 
114
 
 
115
 
 
116
Naming
 
117
======
 
118
 
 
119
Functions, methods or members that are relatively private are given
 
120
a leading underscore prefix.  Names without a leading underscore are
 
121
public not just across modules but to programmers using bzrlib as an
 
122
API.
 
123
 
 
124
We prefer class names to be concatenated capital words (``TestCase``)
 
125
and variables, methods and functions to be lowercase words joined by
 
126
underscores (``revision_id``, ``get_revision``).
 
127
 
 
128
For the purposes of naming some names are treated as single compound
 
129
words: "filename", "revno".
 
130
 
 
131
Consider naming classes as nouns and functions/methods as verbs.
 
132
 
 
133
Try to avoid using abbreviations in names, because there can be
 
134
inconsistency if other people use the full name.
 
135
 
 
136
 
 
137
Standard Names
 
138
==============
 
139
 
 
140
``revision_id`` not ``rev_id`` or ``revid``
 
141
 
 
142
Functions that transform one thing to another should be named ``x_to_y``
 
143
(not ``x2y`` as occurs in some old code.)
 
144
 
 
145
 
 
146
Destructors
 
147
===========
 
148
 
 
149
Python destructors (``__del__``) work differently to those of other
 
150
languages.  In particular, bear in mind that destructors may be called
 
151
immediately when the object apparently becomes unreferenced, or at some
 
152
later time, or possibly never at all.  Therefore we have restrictions on
 
153
what can be done inside them.
 
154
 
 
155
 0. If you think you need to use a ``__del__`` method ask another
 
156
    developer for alternatives.  If you do need to use one, explain
 
157
    why in a comment.
 
158
 
 
159
 1. Never rely on a ``__del__`` method running.  If there is code that
 
160
    must run, do it from a ``finally`` block instead.
 
161
 
 
162
 2. Never ``import`` from inside a ``__del__`` method, or you may crash the
 
163
    interpreter!!
 
164
 
 
165
 3. In some places we raise a warning from the destructor if the object
 
166
    has not been cleaned up or closed.  This is considered OK: the warning
 
167
    may not catch every case but it's still useful sometimes.
 
168
 
 
169
 
 
170
Cleanup methods
 
171
===============
 
172
 
 
173
Often when something has failed later code, including cleanups invoked
 
174
from ``finally`` blocks, will fail too.  These secondary failures are
 
175
generally uninteresting compared to the original exception.  So use the
 
176
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
 
177
are typically called in ``finally`` blocks, such as ``unlock`` methods.
 
178
For example, ``@only_raises(LockNotHeld, LockBroken)``.  All errors that
 
179
are unlikely to be a knock-on failure from a previous failure should be
 
180
allowed.
 
181
 
 
182
 
 
183
Factories
 
184
=========
 
185
 
 
186
In some places we have variables which point to callables that construct
 
187
new instances.  That is to say, they can be used a lot like class objects,
 
188
but they shouldn't be *named* like classes.  Things called ``FooBar`` should
 
189
create an instance of ``FooBar``.  A factory method that might create a
 
190
``FooBar`` or might make something else should be called ``foo_factory``.
 
191
 
 
192
 
 
193
Registries
 
194
==========
 
195
 
 
196
Several places in Bazaar use (or will use) a registry, which is a
 
197
mapping from names to objects or classes.  The registry allows for
 
198
loading in registered code only when it's needed, and keeping
 
199
associated information such as a help string or description.
 
200
 
 
201
 
 
202
InterObject and multiple dispatch
 
203
=================================
 
204
 
 
205
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
 
206
up for example a source and destination repository to find the right way
 
207
to transfer data between them.
 
208
 
 
209
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
 
210
 
 
211
There is a subclass ``InterObject`` classes for each type of object that is
 
212
dispatched this way, e.g. ``InterRepository``.  Calling ``.get()`` on this
 
213
class will return an ``InterObject`` instance providing the best match for
 
214
those parameters, and this instance then has methods for operations
 
215
between the objects.
 
216
 
 
217
::
 
218
 
 
219
  inter = InterRepository.get(source_repo, target_repo)
 
220
  inter.fetch(revision_id)
 
221
 
 
222
``InterRepository`` also acts as a registry-like object for its
 
223
subclasses, and they can be added through ``.register_optimizer``.  The
 
224
right one to run is selected by asking each class, in reverse order of
 
225
registration, whether it ``.is_compatible`` with the relevant objects.
 
226
 
 
227
Lazy Imports
 
228
============
 
229
 
 
230
To make startup time faster, we use the ``bzrlib.lazy_import`` module to
 
231
delay importing modules until they are actually used. ``lazy_import`` uses
 
232
the same syntax as regular python imports. So to import a few modules in a
 
233
lazy fashion do::
 
234
 
 
235
  from bzrlib.lazy_import import lazy_import
 
236
  lazy_import(globals(), """
 
237
  import os
 
238
  import subprocess
 
239
  import sys
 
240
  import time
 
241
 
 
242
  from bzrlib import (
 
243
     errors,
 
244
     transport,
 
245
     revision as _mod_revision,
 
246
     )
 
247
  import bzrlib.transport
 
248
  import bzrlib.xml5
 
249
  """)
 
250
 
 
251
At this point, all of these exist as a ``ImportReplacer`` object, ready to
 
252
be imported once a member is accessed. Also, when importing a module into
 
253
the local namespace, which is likely to clash with variable names, it is
 
254
recommended to prefix it as ``_mod_<module>``. This makes it clearer that
 
255
the variable is a module, and these object should be hidden anyway, since
 
256
they shouldn't be imported into other namespaces.
 
257
 
 
258
While it is possible for ``lazy_import()`` to import members of a module
 
259
when using the ``from module import member`` syntax, it is recommended to
 
260
only use that syntax to load sub modules ``from module import submodule``.
 
261
This is because variables and classes can frequently be used without
 
262
needing a sub-member for example::
 
263
 
 
264
  lazy_import(globals(), """
 
265
  from module import MyClass
 
266
  """)
 
267
 
 
268
  def test(x):
 
269
      return isinstance(x, MyClass)
 
270
 
 
271
This will incorrectly fail, because ``MyClass`` is a ``ImportReplacer``
 
272
object, rather than the real class.
 
273
 
 
274
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
 
275
Because the replacer only knows about the original name, it is unable to
 
276
replace other variables. The ``ImportReplacer`` class will raise an
 
277
``IllegalUseOfScopeReplacer`` exception if it can figure out that this
 
278
happened. But it requires accessing a member more than once from the new
 
279
variable, so some bugs are not detected right away.
 
280
 
 
281
 
 
282
The Null revision
 
283
=================
 
284
 
 
285
The null revision is the ancestor of all revisions.  Its revno is 0, its
 
286
revision-id is ``null:``, and its tree is the empty tree.  When referring
 
287
to the null revision, please use ``bzrlib.revision.NULL_REVISION``.  Old
 
288
code sometimes uses ``None`` for the null revision, but this practice is
 
289
being phased out.
 
290
 
 
291
 
 
292
Object string representations
 
293
=============================
 
294
 
 
295
Python prints objects using their ``__repr__`` method when they are
 
296
written to logs, exception tracebacks, or the debugger.  We want
 
297
objects to have useful representations to help in determining what went
 
298
wrong.
 
299
 
 
300
If you add a new class you should generally add a ``__repr__`` method
 
301
unless there is an adequate method in a parent class.  There should be a
 
302
test for the repr.
 
303
 
 
304
Representations should typically look like Python constructor syntax, but
 
305
they don't need to include every value in the object and they don't need
 
306
to be able to actually execute.  They're to be read by humans, not
 
307
machines.  Don't hardcode the classname in the format, so that we get the
 
308
correct value if the method is inherited by a subclass.  If you're
 
309
printing attributes of the object, including strings, you should normally
 
310
use ``%r`` syntax (to call their repr in turn).
 
311
 
 
312
Try to avoid the representation becoming more than one or two lines long.
 
313
(But balance this against including useful information, and simplicity of
 
314
implementation.)
 
315
 
 
316
Because repr methods are often called when something has already gone
 
317
wrong, they should be written somewhat more defensively than most code.
 
318
The object may be half-initialized or in some other way in an illegal
 
319
state.  The repr method shouldn't raise an exception, or it may hide the
 
320
(probably more useful) underlying exception.
 
321
 
 
322
Example::
 
323
 
 
324
    def __repr__(self):
 
325
        return '%s(%r)' % (self.__class__.__name__,
 
326
                           self._transport)
 
327
 
 
328
 
 
329
Exception handling
 
330
==================
 
331
 
 
332
A bare ``except`` statement will catch all exceptions, including ones that
 
333
really should terminate the program such as ``MemoryError`` and
 
334
``KeyboardInterrupt``.  They should rarely be used unless the exception is
 
335
later re-raised.  Even then, think about whether catching just
 
336
``Exception`` (which excludes system errors in Python2.5 and later) would
 
337
be better.
 
338
 
 
339
 
 
340
Test coverage
 
341
=============
 
342
 
 
343
All code should be exercised by the test suite.  See the `Bazaar Testing
 
344
Guide <http://doc.bazaar.canonical.com/developers/testing.html>`_ for detailed
 
345
information about writing tests.
 
346
 
 
347
 
 
348
Assertions
 
349
==========
 
350
 
 
351
Do not use the Python ``assert`` statement, either in tests or elsewhere.
 
352
A source test checks that it is not used.  It is ok to explicitly raise
 
353
AssertionError.
 
354
 
 
355
Rationale:
 
356
 
 
357
 * It makes the behaviour vary depending on whether bzr is run with -O
 
358
   or not, therefore giving a chance for bugs that occur in one case or
 
359
   the other, several of which have already occurred: assertions with
 
360
   side effects, code which can't continue unless the assertion passes,
 
361
   cases where we should give the user a proper message rather than an
 
362
   assertion failure.
 
363
 * It's not that much shorter than an explicit if/raise.
 
364
 * It tends to lead to fuzzy thinking about whether the check is
 
365
   actually needed or not, and whether it's an internal error or not
 
366
 * It tends to cause look-before-you-leap patterns.
 
367
 * It's unsafe if the check is needed to protect the integrity of the
 
368
   user's data.
 
369
 * It tends to give poor messages since the developer can get by with
 
370
   no explanatory text at all.
 
371
 * We can't rely on people always running with -O in normal use, so we
 
372
   can't use it for tests that are actually expensive.
 
373
 * Expensive checks that help developers are better turned on from the
 
374
   test suite or a -D flag.
 
375
 * If used instead of ``self.assert*()`` in tests it makes them falsely pass with -O.
 
376
 
 
377
emacs setup
 
378
===========
 
379
 
 
380
In emacs::
 
381
 
 
382
    ;(defface my-invalid-face
 
383
    ;  '((t (:background "Red" :underline t)))
 
384
    ;  "Face used to highlight invalid constructs or other uglyties"
 
385
    ;  )
 
386
 
 
387
    (defun my-python-mode-hook ()
 
388
     ;; setup preferred indentation style.
 
389
     (setq fill-column 79)
 
390
     (setq indent-tabs-mode nil) ; no tabs, never, I will not repeat
 
391
    ;  (font-lock-add-keywords 'python-mode
 
392
    ;                         '(("^\\s *\t" . 'my-invalid-face) ; Leading tabs
 
393
    ;                            ("[ \t]+$" . 'my-invalid-face)  ; Trailing spaces
 
394
    ;                            ("^[ \t]+$" . 'my-invalid-face)); Spaces only
 
395
    ;                          )
 
396
     )
 
397
 
 
398
    (add-hook 'python-mode-hook 'my-python-mode-hook)
 
399
 
 
400
The lines beginning with ';' are comments. They can be activated
 
401
if one want to have a strong notice of some tab/space usage
 
402
violations.
 
403
 
 
404
Portability Tips
 
405
================
 
406
 
 
407
The ``bzrlib.osutils`` module has many useful helper functions, including
 
408
some more portable variants of functions in the standard library.
 
409
 
 
410
In particular, don't use ``shutil.rmtree`` unless it's acceptable for it
 
411
to fail on Windows if some files are readonly or still open elsewhere.
 
412
Use ``bzrlib.osutils.rmtree`` instead.
 
413
 
 
414
Using the ``open(..).read(..)`` or ``open(..).write(..)`` style chaining
 
415
of methods for reading or writing file content relies on garbage collection
 
416
to close the file which may keep the file open for an undefined period of
 
417
time. This may break some follow up operations like rename on Windows.
 
418
Use ``try/finally`` to explictly close the file. E.g.::
 
419
 
 
420
    f = open('foo.txt', 'w')
 
421
    try:
 
422
        f.write(s)
 
423
    finally:
 
424
        f.close()
 
425
 
 
426
..
 
427
   vim: ft=rst tw=74 ai