← 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: Patch Queue Manager
  • Date: 2011-09-22 14:12:18 UTC
  • mfrom: (6155.3.1 jam)
  • Revision ID: pqm@pqm.ubuntu.com-20110922141218-86s4uu6nqvourw4f
(jameinel) Cleanup comments bzrlib/smart/__init__.py (John A Meinel)

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, do it from a ``finally`` block instead.
 
192
   must run, instead have a ``finally`` block or an ``addCleanup`` call an
 
193
   explicit ``close`` method.
193
194
 
194
195
2. Never ``import`` from inside a ``__del__`` method, or you may crash the
195
196
   interpreter!!
196
197
 
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
 
 
 
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__``.
201
207
 
202
208
Cleanup methods
203
209
===============
364
370
 
365
371
Because repr methods are often called when something has already gone
366
372
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.
367
375
The object may be half-initialized or in some other way in an illegal
368
376
state.  The repr method shouldn't raise an exception, or it may hide the
369
377
(probably more useful) underlying exception.
385
393
``Exception`` (which excludes system errors in Python2.5 and later) would
386
394
be better.
387
395
 
 
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
 
388
403
 
389
404
Test coverage
390
405
=============
485
500
 
486
501
 * Don't say "open source" when you mean "free software".
487
502
 
 
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
 
488
517
..
489
518
   vim: ft=rst tw=74 ai