1
***********************
2
Bazaar Code Style Guide
3
***********************
8
Please write PEP-8__ compliant code.
10
__ http://www.python.org/peps/pep-0008.html
12
One often-missed requirement is that the first line of docstrings
13
should be a self-contained one-sentence summary.
15
We use 4 space indents for blocks, and never use tab characters. (In vim,
18
Trailing white space should be avoided, but is allowed.
19
You should however not make lots of unrelated white space changes.
21
Unix style newlines (LF) are used.
23
Each file must have a newline at the end of it.
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
29
within the parenthesis or other character that opens the block, e.g.::
35
or indented by four spaces::
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
46
self.legbone.kneebone.shinbone.toebone.shake_it(one,
52
self.legbone.kneebone.shinbone.toebone.shake_it(one,
58
self.legbone.kneebone.shinbone.toebone.shake_it(
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
65
from bzrlib.goo import (
71
There should be spaces between function parameters, but not between the
72
keyword name and the value::
74
call(1, 3, cheese=quark)
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.)
87
* don't use the ``with`` statement
88
* don't ``from . import``
94
``hasattr`` should not be used because it swallows exceptions including
95
``KeyboardInterrupt``. Instead, say something like ::
97
if getattr(thing, 'name', None) is None
103
* Imports should be done at the top-level of the file, unless there is
104
a strong reason to have them lazily loaded when a particular
105
function runs. Import statements have a cost, so try to make sure
106
they don't run inside hot functions.
108
* Module names should always be given fully-qualified,
109
i.e. ``bzrlib.hashcache`` not just ``hashcache``.
115
Functions, methods or members that are relatively private are given
116
a leading underscore prefix. Names without a leading underscore are
117
public not just across modules but to programmers using bzrlib as an
120
We prefer class names to be concatenated capital words (``TestCase``)
121
and variables, methods and functions to be lowercase words joined by
122
underscores (``revision_id``, ``get_revision``).
124
For the purposes of naming some names are treated as single compound
125
words: "filename", "revno".
127
Consider naming classes as nouns and functions/methods as verbs.
129
Try to avoid using abbreviations in names, because there can be
130
inconsistency if other people use the full name.
136
``revision_id`` not ``rev_id`` or ``revid``
138
Functions that transform one thing to another should be named ``x_to_y``
139
(not ``x2y`` as occurs in some old code.)
145
Python destructors (``__del__``) work differently to those of other
146
languages. In particular, bear in mind that destructors may be called
147
immediately when the object apparently becomes unreferenced, or at some
148
later time, or possibly never at all. Therefore we have restrictions on
149
what can be done inside them.
151
0. If you think you need to use a ``__del__`` method ask another
152
developer for alternatives. If you do need to use one, explain
155
1. Never rely on a ``__del__`` method running. If there is code that
156
must run, do it from a ``finally`` block instead.
158
2. Never ``import`` from inside a ``__del__`` method, or you may crash the
161
3. In some places we raise a warning from the destructor if the object
162
has not been cleaned up or closed. This is considered OK: the warning
163
may not catch every case but it's still useful sometimes.
169
Often when something has failed later code, including cleanups invoked
170
from ``finally`` blocks, will fail too. These secondary failures are
171
generally uninteresting compared to the original exception. So use the
172
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
173
are typically called in ``finally`` blocks, such as ``unlock`` methods.
174
For example, ``@only_raises(LockNotHeld, LockBroken)``. All errors that
175
are unlikely to be a knock-on failure from a previous failure should be
182
In some places we have variables which point to callables that construct
183
new instances. That is to say, they can be used a lot like class objects,
184
but they shouldn't be *named* like classes. Things called ``FooBar`` should
185
create an instance of ``FooBar``. A factory method that might create a
186
``FooBar`` or might make something else should be called ``foo_factory``.
192
Several places in Bazaar use (or will use) a registry, which is a
193
mapping from names to objects or classes. The registry allows for
194
loading in registered code only when it's needed, and keeping
195
associated information such as a help string or description.
198
InterObject and multiple dispatch
199
=================================
201
The ``InterObject`` provides for two-way `multiple dispatch`__: matching
202
up for example a source and destination repository to find the right way
203
to transfer data between them.
205
.. __: http://en.wikipedia.org/wiki/Multiple_dispatch
207
There is a subclass ``InterObject`` classes for each type of object that is
208
dispatched this way, e.g. ``InterRepository``. Calling ``.get()`` on this
209
class will return an ``InterObject`` instance providing the best match for
210
those parameters, and this instance then has methods for operations
215
inter = InterRepository.get(source_repo, target_repo)
216
inter.fetch(revision_id)
218
``InterRepository`` also acts as a registry-like object for its
219
subclasses, and they can be added through ``.register_optimizer``. The
220
right one to run is selected by asking each class, in reverse order of
221
registration, whether it ``.is_compatible`` with the relevant objects.
226
To make startup time faster, we use the ``bzrlib.lazy_import`` module to
227
delay importing modules until they are actually used. ``lazy_import`` uses
228
the same syntax as regular python imports. So to import a few modules in a
231
from bzrlib.lazy_import import lazy_import
232
lazy_import(globals(), """
241
revision as _mod_revision,
243
import bzrlib.transport
247
At this point, all of these exist as a ``ImportReplacer`` object, ready to
248
be imported once a member is accessed. Also, when importing a module into
249
the local namespace, which is likely to clash with variable names, it is
250
recommended to prefix it as ``_mod_<module>``. This makes it clearer that
251
the variable is a module, and these object should be hidden anyway, since
252
they shouldn't be imported into other namespaces.
254
While it is possible for ``lazy_import()`` to import members of a module
255
when using the ``from module import member`` syntax, it is recommended to
256
only use that syntax to load sub modules ``from module import submodule``.
257
This is because variables and classes can frequently be used without
258
needing a sub-member for example::
260
lazy_import(globals(), """
261
from module import MyClass
265
return isinstance(x, MyClass)
267
This will incorrectly fail, because ``MyClass`` is a ``ImportReplacer``
268
object, rather than the real class.
270
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
271
Because the replacer only knows about the original name, it is unable to
272
replace other variables. The ``ImportReplacer`` class will raise an
273
``IllegalUseOfScopeReplacer`` exception if it can figure out that this
274
happened. But it requires accessing a member more than once from the new
275
variable, so some bugs are not detected right away.
281
The null revision is the ancestor of all revisions. Its revno is 0, its
282
revision-id is ``null:``, and its tree is the empty tree. When referring
283
to the null revision, please use ``bzrlib.revision.NULL_REVISION``. Old
284
code sometimes uses ``None`` for the null revision, but this practice is
288
Object string representations
289
=============================
291
Python prints objects using their ``__repr__`` method when they are
292
written to logs, exception tracebacks, or the debugger. We want
293
objects to have useful representations to help in determining what went
296
If you add a new class you should generally add a ``__repr__`` method
297
unless there is an adequate method in a parent class. There should be a
300
Representations should typically look like Python constructor syntax, but
301
they don't need to include every value in the object and they don't need
302
to be able to actually execute. They're to be read by humans, not
303
machines. Don't hardcode the classname in the format, so that we get the
304
correct value if the method is inherited by a subclass. If you're
305
printing attributes of the object, including strings, you should normally
306
use ``%r`` syntax (to call their repr in turn).
308
Try to avoid the representation becoming more than one or two lines long.
309
(But balance this against including useful information, and simplicity of
312
Because repr methods are often called when something has already gone
313
wrong, they should be written somewhat more defensively than most code.
314
The object may be half-initialized or in some other way in an illegal
315
state. The repr method shouldn't raise an exception, or it may hide the
316
(probably more useful) underlying exception.
321
return '%s(%r)' % (self.__class__.__name__,
328
A bare ``except`` statement will catch all exceptions, including ones that
329
really should terminate the program such as ``MemoryError`` and
330
``KeyboardInterrupt``. They should rarely be used unless the exception is
331
later re-raised. Even then, think about whether catching just
332
``Exception`` (which excludes system errors in Python2.5 and later) would
339
All code should be exercised by the test suite. See the `Bazaar Testing
340
Guide <http://doc.bazaar-vcs.org/developers/testing.html>`_ for detailed
341
information about writing tests.
347
Do not use the Python ``assert`` statement, either in tests or elsewhere.
348
A source test checks that it is not used. It is ok to explicitly raise
353
* It makes the behaviour vary depending on whether bzr is run with -O
354
or not, therefore giving a chance for bugs that occur in one case or
355
the other, several of which have already occurred: assertions with
356
side effects, code which can't continue unless the assertion passes,
357
cases where we should give the user a proper message rather than an
359
* It's not that much shorter than an explicit if/raise.
360
* It tends to lead to fuzzy thinking about whether the check is
361
actually needed or not, and whether it's an internal error or not
362
* It tends to cause look-before-you-leap patterns.
363
* It's unsafe if the check is needed to protect the integrity of the
365
* It tends to give poor messages since the developer can get by with
366
no explanatory text at all.
367
* We can't rely on people always running with -O in normal use, so we
368
can't use it for tests that are actually expensive.
369
* Expensive checks that help developers are better turned on from the
370
test suite or a -D flag.
371
* If used instead of ``self.assert*()`` in tests it makes them falsely pass with -O.
378
;(defface my-invalid-face
379
; '((t (:background "Red" :underline t)))
380
; "Face used to highlight invalid constructs or other uglyties"
383
(defun my-python-mode-hook ()
384
;; setup preferred indentation style.
385
(setq fill-column 79)
386
(setq indent-tabs-mode nil) ; no tabs, never, I will not repeat
387
; (font-lock-add-keywords 'python-mode
388
; '(("^\\s *\t" . 'my-invalid-face) ; Leading tabs
389
; ("[ \t]+$" . 'my-invalid-face) ; Trailing spaces
390
; ("^[ \t]+$" . 'my-invalid-face)); Spaces only
394
(add-hook 'python-mode-hook 'my-python-mode-hook)
396
The lines beginning with ';' are comments. They can be activated
397
if one want to have a strong notice of some tab/space usage
403
The ``bzrlib.osutils`` module has many useful helper functions, including
404
some more portable variants of functions in the standard library.
406
In particular, don't use ``shutil.rmtree`` unless it's acceptable for it
407
to fail on Windows if some files are readonly or still open elsewhere.
408
Use ``bzrlib.osutils.rmtree`` instead.
added
removed
doc/developers/code-style.txt
