← 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: John Arbash Meinel
  • Date: 2010-09-25 20:08:01 UTC
  • mfrom: (5444 +trunk)
  • mto: This revision was merged to the branch mainline in revision 5445.
  • Revision ID: john@arbash-meinel.com-20100925200801-7uf0ux3uwxo9i3x0
Merge bzr.dev 5444 to resolve some small text conflicts.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/code-style.txt
101
101
  if getattr(thing, 'name', None) is None
102
102
 
103
103
 
 
104
kwargs
 
105
======
 
106
 
 
107
``**kwargs`` in the prototype of a function should be used sparingly.
 
108
It can be good on higher-order functions that decorate other functions,
 
109
such as ``addCleanup`` or ``assertRaises``, or on functions that take only
 
110
(or almost only) kwargs, where any kwargs can be passed.  
 
111
 
 
112
Otherwise, be careful: if the parameters to a function are a bit complex
 
113
and might vary over time (e.g.  the ``commit`` API) then we prefer to pass an
 
114
object rather than a bag of positional and/or keyword args.  If you have
 
115
an arbitrary set of keys and values that are different with each use (e.g.
 
116
string interpolation inputs) then again that should not be mixed in with
 
117
the regular positional/keyword args, it seems like a different category of
 
118
thing.
 
119
 
 
120
 
 
121
Imitating standard objects
 
122
==========================
 
123
 
 
124
Don't provide methods that imitate built-in classes (eg ``__in__``,
 
125
``__call__``, ``__int__``, ``__getitem__``) unless the class you're
 
126
implementing really does act like the builtin class, in semantics and
 
127
performance.
 
128
 
 
129
For example, old code lets you say ``file_id in inv`` but we no longer
 
130
consider this good style.  Instead, say more explicitly
 
131
``inv.has_id(file_id)``.
 
132
 
 
133
``__repr__``, ``__cmp__``, ``__str__`` are usually fine.
 
134
 
 
135
 
104
136
Module Imports
105
137
==============
106
138