← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Vincent Ladeuil
  • Date: 2010-10-07 06:08:01 UTC
  • mto: This revision was merged to the branch mainline in revision 5491.
  • Revision ID: v.ladeuil+lp@free.fr-20101007060801-wfdhizfhfmctl8qa
Fix some typos and propose a release planning.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/code-style.txt
189
189
   why in a comment.
190
190
 
191
191
1. Never rely on a ``__del__`` method running.  If there is code that
192
 
   must run, instead have a ``finally`` block or an ``addCleanup`` call an
193
 
   explicit ``close`` method.
 
192
   must run, do it from a ``finally`` block instead.
194
193
 
195
194
2. Never ``import`` from inside a ``__del__`` method, or you may crash the
196
195
   interpreter!!
197
196
 
198
 
3. Prior to bzr 2.4, we sometimes used to raise warnings from del methods
199
 
   that the object was not cleaned up or closed.  We no longer do this:
200
 
   failure to close the object doesn't cause a test failure; the warning
201
 
   appears an arbitrary long time after the problem occurred (the object
202
 
   being leaked); merely having a del method inhibits Python gc; the
203
 
   warnings appear to users and upset them; they can also break tests that
204
 
   are checking what appears on stderr.
205
 
   
206
 
In short, just don't use ``__del__``.
 
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.
 
200
 
207
201
 
208
202
Cleanup methods
209
203
===============
370
364
 
371
365
Because repr methods are often called when something has already gone
372
366
wrong, they should be written somewhat more defensively than most code.
373
 
They shouldn't have side effects like doing network or disk
374
 
IO.
375
367
The object may be half-initialized or in some other way in an illegal
376
368
state.  The repr method shouldn't raise an exception, or it may hide the
377
369
(probably more useful) underlying exception.
393
385
``Exception`` (which excludes system errors in Python2.5 and later) would
394
386
be better.
395
387
 
396
 
The ``__str__`` method on exceptions should be small and have no side
397
 
effects, following the rules given for `Object string representations`_.
398
 
In particular it should not do any network IO, or complicated
399
 
introspection of other objects.  All the state needed to present the
400
 
exception to the user should be gathered before the error is raised.
401
 
In other words, exceptions should basically be value objects.
402
 
 
403
388
 
404
389
Test coverage
405
390
=============
500
485
 
501
486
 * Don't say "open source" when you mean "free software".
502
487
 
503
 
 
504
 
Dynamic imports
505
 
===============
506
 
 
507
 
If you need to import a module (or attribute of a module) named in a
508
 
variable:
509
 
 
510
 
 * If importing a module, not an attribute, and the module is a top-level
511
 
   module (i.e. has no dots in the name), then it's ok to use the builtin
512
 
   ``__import__``, e.g. ``__import__(module_name)``.
513
 
 * In all other cases, prefer ``bzrlib.pyutils.get_named_object`` to the
514
 
   built-in ``__import__``.  ``__import__`` has some subtleties and
515
 
   unintuitive behaviours that make it hard to use correctly.
516
 
 
517
488
..
518
489
   vim: ft=rst tw=74 ai