/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

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

  • Committer: Andrew Bennetts
  • Date: 2011-06-09 07:38:32 UTC
  • mto: This revision was merged to the branch mainline in revision 5964.
  • Revision ID: andrew.bennetts@canonical.com-20110609073832-dt6oww033iexli4l
Fix thinko in wording regarding stacking invariants and revisions with multiple parents.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/code-style.txt
1
1
***********************
2
 
Breezy Code Style Guide
 
2
Bazaar Code Style Guide
3
3
***********************
4
4
 
5
5
Code layout
62
62
character on the following line.  This makes it easier to add new items in
63
63
future::
64
64
 
65
 
    from breezy.goo import (
 
65
    from bzrlib.goo import (
66
66
        jam,
67
67
        jelly,
68
68
        marmalade,
77
77
Python versions
78
78
===============
79
79
 
80
 
Breezy supports Python 2.7 and Python 3.5 or later.
 
80
Bazaar supports Python from 2.4 through 2.6, and in the future we want to
 
81
support Python 2.7 and 3.0.  Avoid using language features added in 2.5,
 
82
2.6 or 2.7, or features deprecated in Python 3.0.  (You can check v3
 
83
compatibility using 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
 
81
94
 
82
95
hasattr and getattr
83
96
===================
94
107
``**kwargs`` in the prototype of a function should be used sparingly.
95
108
It can be good on higher-order functions that decorate other functions,
96
109
such as ``addCleanup`` or ``assertRaises``, or on functions that take only
97
 
(or almost only) kwargs, where any kwargs can be passed. 
 
110
(or almost only) kwargs, where any kwargs can be passed.  
98
111
 
99
112
Otherwise, be careful: if the parameters to a function are a bit complex
100
113
and might vary over time (e.g.  the ``commit`` API) then we prefer to pass an
129
142
  they don't run inside hot functions.
130
143
 
131
144
* Module names should always be given fully-qualified,
132
 
  i.e. ``breezy.hashcache`` not just ``hashcache``.
 
145
  i.e. ``bzrlib.hashcache`` not just ``hashcache``.
133
146
 
134
147
 
135
148
Naming
137
150
 
138
151
Functions, methods or members that are relatively private are given
139
152
a leading underscore prefix.  Names without a leading underscore are
140
 
public not just across modules but to programmers using breezy as an
 
153
public not just across modules but to programmers using bzrlib as an
141
154
API.
142
155
 
143
156
We prefer class names to be concatenated capital words (``TestCase``)
176
189
   why in a comment.
177
190
 
178
191
1. Never rely on a ``__del__`` method running.  If there is code that
179
 
   must run, instead have a ``finally`` block or an ``addCleanup`` call an
180
 
   explicit ``close`` method.
 
192
   must run, do it from a ``finally`` block instead.
181
193
 
182
194
2. Never ``import`` from inside a ``__del__`` method, or you may crash the
183
195
   interpreter!!
184
196
 
185
 
3. Prior to bzr 2.4, we sometimes used to raise warnings from del methods
186
 
   that the object was not cleaned up or closed.  We no longer do this:
187
 
   failure to close the object doesn't cause a test failure; the warning
188
 
   appears an arbitrary long time after the problem occurred (the object
189
 
   being leaked); merely having a del method inhibits Python gc; the
190
 
   warnings appear to users and upset them; they can also break tests that
191
 
   are checking what appears on stderr.
 
197
3. In some places we raise a warning from the destructor if the object
 
198
   has not been cleaned up or closed.  This is considered OK: the warning
 
199
   may not catch every case but it's still useful sometimes.
192
200
 
193
 
In short, just don't use ``__del__``.
194
201
 
195
202
Cleanup methods
196
203
===============
197
204
 
198
205
Often when something has failed later code will fail too, including
199
206
cleanups invoked from ``finally`` blocks.  These secondary failures are
200
 
generally uninteresting compared to the original exception.  ``breezy``
 
207
generally uninteresting compared to the original exception.  ``bzrlib``
201
208
has some facilities you can use to mitigate this.
202
209
 
203
210
* In ``Command`` subclasses, prefer the ``add_cleanup`` method to using
211
218
  acquire/release) because there isn't a large block of code separating
212
219
  them.
213
220
 
214
 
* Use the ``only_raises`` decorator (from ``breezy.decorators``) when
 
221
* Use the ``only_raises`` decorator (from ``bzrlib.decorators``) when
215
222
  defining methods that are typically called in ``finally`` blocks, such
216
223
  as ``unlock`` methods.  For example, ``@only_raises(LockNotHeld,
217
224
  LockBroken)``.  All errors that are unlikely to be a knock-on failure
218
225
  from a previous failure should be allowed.
219
226
 
220
227
* Consider using the ``OperationWithCleanups`` helper from
221
 
  ``breezy.cleanup`` anywhere else you have a ``finally`` block that
 
228
  ``bzrlib.cleanup`` anywhere else you have a ``finally`` block that
222
229
  might fail.
223
230
 
224
231
 
235
242
Registries
236
243
==========
237
244
 
238
 
Several places in Breezy use (or will use) a registry, which is a
 
245
Several places in Bazaar use (or will use) a registry, which is a
239
246
mapping from names to objects or classes.  The registry allows for
240
247
loading in registered code only when it's needed, and keeping
241
248
associated information such as a help string or description.
269
276
Lazy Imports
270
277
============
271
278
 
272
 
To make startup time faster, we use the ``breezy.lazy_import`` module to
 
279
To make startup time faster, we use the ``bzrlib.lazy_import`` module to
273
280
delay importing modules until they are actually used. ``lazy_import`` uses
274
281
the same syntax as regular python imports. So to import a few modules in a
275
282
lazy fashion do::
276
283
 
277
 
  from breezy.lazy_import import lazy_import
 
284
  from bzrlib.lazy_import import lazy_import
278
285
  lazy_import(globals(), """
279
286
  import os
280
287
  import subprocess
281
288
  import sys
282
289
  import time
283
290
 
284
 
  from breezy import (
 
291
  from bzrlib import (
285
292
     errors,
286
293
     transport,
287
294
     revision as _mod_revision,
288
295
     )
289
 
  import breezy.transport
290
 
  import breezy.xml5
 
296
  import bzrlib.transport
 
297
  import bzrlib.xml5
291
298
  """)
292
299
 
293
300
At this point, all of these exist as a ``ImportReplacer`` object, ready to
326
333
 
327
334
The null revision is the ancestor of all revisions.  Its revno is 0, its
328
335
revision-id is ``null:``, and its tree is the empty tree.  When referring
329
 
to the null revision, please use ``breezy.revision.NULL_REVISION``.  Old
 
336
to the null revision, please use ``bzrlib.revision.NULL_REVISION``.  Old
330
337
code sometimes uses ``None`` for the null revision, but this practice is
331
338
being phased out.
332
339
 
391
398
Test coverage
392
399
=============
393
400
 
394
 
All code should be exercised by the test suite.  See the `Breezy Testing
395
 
Guide <http://www.breezy-vcs.org/developers/testing.html>`_ for detailed
 
401
All code should be exercised by the test suite.  See the `Bazaar Testing
 
402
Guide <http://doc.bazaar.canonical.com/developers/testing.html>`_ for detailed
396
403
information about writing tests.
397
404
 
398
405
 
405
412
 
406
413
Rationale:
407
414
 
408
 
* It makes the behaviour vary depending on whether brz is run with -O
 
415
* It makes the behaviour vary depending on whether bzr is run with -O
409
416
  or not, therefore giving a chance for bugs that occur in one case or
410
417
  the other, several of which have already occurred: assertions with
411
418
  side effects, code which can't continue unless the assertion passes,
456
463
Portability Tips
457
464
================
458
465
 
459
 
The ``breezy.osutils`` module has many useful helper functions, including
 
466
The ``bzrlib.osutils`` module has many useful helper functions, including
460
467
some more portable variants of functions in the standard library.
461
468
 
462
469
In particular, don't use ``shutil.rmtree`` unless it's acceptable for it
463
470
to fail on Windows if some files are readonly or still open elsewhere.
464
 
Use ``breezy.osutils.rmtree`` instead.
 
471
Use ``bzrlib.osutils.rmtree`` instead.
465
472
 
466
473
Using the ``open(..).read(..)`` or ``open(..).write(..)`` style chaining
467
474
of methods for reading or writing file content relies on garbage collection
476
483
        f.close()
477
484
 
478
485
 
 
486
Terminology
 
487
===========
 
488
 
 
489
Bazaar is a GNU project and uses standard GNU terminology, especially:
 
490
 
 
491
 * Use the word "Linux" to refer to the Linux kernel, not as a synechoche
 
492
   for the entire operating system.  (See `bug 528253
 
493
   <https://bugs.launchpad.net/bzr/+bug/528253>`_).
 
494
 
 
495
 * Don't say "open source" when you mean "free software".
 
496
 
 
497
 
479
498
Dynamic imports
480
499
===============
481
500
 
485
504
 * If importing a module, not an attribute, and the module is a top-level
486
505
   module (i.e. has no dots in the name), then it's ok to use the builtin
487
506
   ``__import__``, e.g. ``__import__(module_name)``.
488
 
 * In all other cases, prefer ``breezy.pyutils.get_named_object`` to the
 
507
 * In all other cases, prefer ``bzrlib.pyutils.get_named_object`` to the
489
508
   built-in ``__import__``.  ``__import__`` has some subtleties and
490
509
   unintuitive behaviours that make it hard to use correctly.
491
510