/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: Richard Wilbur
  • Date: 2016-02-04 19:07:28 UTC
  • mto: This revision was merged to the branch mainline in revision 6618.
  • Revision ID: richard.wilbur@gmail.com-20160204190728-p0zvfii6zase0fw7
Update COPYING.txt from the original http://www.gnu.org/licenses/gpl-2.0.txt  (Only differences were in whitespace.)  Thanks to Petr Stodulka for pointing out the discrepancy.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/code-style.txt
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,
98
98
``**kwargs`` in the prototype of a function should be used sparingly.
99
99
It can be good on higher-order functions that decorate other functions,
100
100
such as ``addCleanup`` or ``assertRaises``, or on functions that take only
101
 
(or almost only) kwargs, where any kwargs can be passed. 
 
101
(or almost only) kwargs, where any kwargs can be passed.  
102
102
 
103
103
Otherwise, be careful: if the parameters to a function are a bit complex
104
104
and might vary over time (e.g.  the ``commit`` API) then we prefer to pass an
133
133
  they don't run inside hot functions.
134
134
 
135
135
* Module names should always be given fully-qualified,
136
 
  i.e. ``breezy.hashcache`` not just ``hashcache``.
 
136
  i.e. ``bzrlib.hashcache`` not just ``hashcache``.
137
137
 
138
138
 
139
139
Naming
141
141
 
142
142
Functions, methods or members that are relatively private are given
143
143
a leading underscore prefix.  Names without a leading underscore are
144
 
public not just across modules but to programmers using breezy as an
 
144
public not just across modules but to programmers using bzrlib as an
145
145
API.
146
146
 
147
147
We prefer class names to be concatenated capital words (``TestCase``)
193
193
   being leaked); merely having a del method inhibits Python gc; the
194
194
   warnings appear to users and upset them; they can also break tests that
195
195
   are checking what appears on stderr.
196
 
  
 
196
   
197
197
In short, just don't use ``__del__``.
198
198
 
199
199
Cleanup methods
201
201
 
202
202
Often when something has failed later code will fail too, including
203
203
cleanups invoked from ``finally`` blocks.  These secondary failures are
204
 
generally uninteresting compared to the original exception.  ``breezy``
 
204
generally uninteresting compared to the original exception.  ``bzrlib``
205
205
has some facilities you can use to mitigate this.
206
206
 
207
207
* In ``Command`` subclasses, prefer the ``add_cleanup`` method to using
215
215
  acquire/release) because there isn't a large block of code separating
216
216
  them.
217
217
 
218
 
* Use the ``only_raises`` decorator (from ``breezy.decorators``) when
 
218
* Use the ``only_raises`` decorator (from ``bzrlib.decorators``) when
219
219
  defining methods that are typically called in ``finally`` blocks, such
220
220
  as ``unlock`` methods.  For example, ``@only_raises(LockNotHeld,
221
221
  LockBroken)``.  All errors that are unlikely to be a knock-on failure
222
222
  from a previous failure should be allowed.
223
223
 
224
224
* Consider using the ``OperationWithCleanups`` helper from
225
 
  ``breezy.cleanup`` anywhere else you have a ``finally`` block that
 
225
  ``bzrlib.cleanup`` anywhere else you have a ``finally`` block that
226
226
  might fail.
227
227
 
228
228
 
273
273
Lazy Imports
274
274
============
275
275
 
276
 
To make startup time faster, we use the ``breezy.lazy_import`` module to
 
276
To make startup time faster, we use the ``bzrlib.lazy_import`` module to
277
277
delay importing modules until they are actually used. ``lazy_import`` uses
278
278
the same syntax as regular python imports. So to import a few modules in a
279
279
lazy fashion do::
280
280
 
281
 
  from breezy.lazy_import import lazy_import
 
281
  from bzrlib.lazy_import import lazy_import
282
282
  lazy_import(globals(), """
283
283
  import os
284
284
  import subprocess
285
285
  import sys
286
286
  import time
287
287
 
288
 
  from breezy import (
 
288
  from bzrlib import (
289
289
     errors,
290
290
     transport,
291
291
     revision as _mod_revision,
292
292
     )
293
 
  import breezy.transport
294
 
  import breezy.xml5
 
293
  import bzrlib.transport
 
294
  import bzrlib.xml5
295
295
  """)
296
296
 
297
297
At this point, all of these exist as a ``ImportReplacer`` object, ready to
330
330
 
331
331
The null revision is the ancestor of all revisions.  Its revno is 0, its
332
332
revision-id is ``null:``, and its tree is the empty tree.  When referring
333
 
to the null revision, please use ``breezy.revision.NULL_REVISION``.  Old
 
333
to the null revision, please use ``bzrlib.revision.NULL_REVISION``.  Old
334
334
code sometimes uses ``None`` for the null revision, but this practice is
335
335
being phased out.
336
336
 
460
460
Portability Tips
461
461
================
462
462
 
463
 
The ``breezy.osutils`` module has many useful helper functions, including
 
463
The ``bzrlib.osutils`` module has many useful helper functions, including
464
464
some more portable variants of functions in the standard library.
465
465
 
466
466
In particular, don't use ``shutil.rmtree`` unless it's acceptable for it
467
467
to fail on Windows if some files are readonly or still open elsewhere.
468
 
Use ``breezy.osutils.rmtree`` instead.
 
468
Use ``bzrlib.osutils.rmtree`` instead.
469
469
 
470
470
Using the ``open(..).read(..)`` or ``open(..).write(..)`` style chaining
471
471
of methods for reading or writing file content relies on garbage collection
480
480
        f.close()
481
481
 
482
482
 
 
483
Terminology
 
484
===========
 
485
 
 
486
Bazaar is a GNU project and uses standard GNU terminology, especially:
 
487
 
 
488
 * Use the word "Linux" to refer to the Linux kernel, not as a synechoche
 
489
   for the entire operating system.  (See `bug 528253
 
490
   <https://bugs.launchpad.net/bzr/+bug/528253>`_).
 
491
 
 
492
 * Don't say "open source" when you mean "free software".
 
493
 
 
494
 
483
495
Dynamic imports
484
496
===============
485
497
 
489
501
 * If importing a module, not an attribute, and the module is a top-level
490
502
   module (i.e. has no dots in the name), then it's ok to use the builtin
491
503
   ``__import__``, e.g. ``__import__(module_name)``.
492
 
 * In all other cases, prefer ``breezy.pyutils.get_named_object`` to the
 
504
 * In all other cases, prefer ``bzrlib.pyutils.get_named_object`` to the
493
505
   built-in ``__import__``.  ``__import__`` has some subtleties and
494
506
   unintuitive behaviours that make it hard to use correctly.
495
507