← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Martin Pool
  • Date: 2005-10-06 03:37:36 UTC
  • mto: (1185.13.3)
  • mto: This revision was merged to the branch mainline in revision 1417.
  • Revision ID: mbp@sourcefrog.net-20051006033736-d3d9bfcf41f5cc45
- notes from coding-convention discussion

Show diffs side-by-side

added added

removed removed

Lines of Context:
HACKING
1
1
============================
2
 
guidelines for modifying bzr
 
2
Guidelines for modifying bzr
3
3
============================
4
4
 
 
5
.. contents::
 
6
 
 
7
(The current version of this document is available in the file ``HACKING``
 
8
in the source tree, or at http://bazaar-ng.org/hacking.html)
 
9
 
 
10
Overall
 
11
=======
 
12
 
5
13
* New functionality should have test cases.  Preferably write the
6
14
  test before writing the code.
7
15
 
20
28
  function runs.  Import statements have a cost, so try to make sure
21
29
  they don't run inside hot functions.
22
30
 
23
 
* Please write PEP-8__ compliant code.  
24
 
 
25
 
  One often-missed requirement is that the first line of docstrings
26
 
  should be a self-contained one-sentence summary.
27
 
 
28
 
__ http://www.python.org/peps/pep-0008.html
29
 
 
30
31
* Module names should always be given fully-qualified,
31
32
  i.e. ``bzrlib.hashcache`` not just ``hashcache``.
32
33
 
46
47
should be done.
47
48
 
48
49
 
 
50
API documentation
 
51
-----------------
 
52
 
 
53
Functions, methods, classes and modules should have docstrings
 
54
describing how they are used. 
 
55
 
 
56
The first line of the docstring should be a self-contained sentence.
 
57
 
 
58
For the special case of Command classes, this acts as the user-visible
 
59
documentation shown by the help command.
 
60
 
 
61
The docstrings should be formatted as reStructuredText_ (like this
 
62
document), suitable for processing using the epydoc_ tool into HTML
 
63
documentation.
 
64
 
 
65
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
66
.. _epydoc: http://epydoc.sourceforge.net/
 
67
 
 
68
 
 
69
 
 
70
Coding style
 
71
============
 
72
 
 
73
Please write PEP-8__ compliant code.  
 
74
 
 
75
One often-missed requirement is that the first line of docstrings
 
76
should be a self-contained one-sentence summary.
 
77
 
 
78
__ http://www.python.org/peps/pep-0008.html
 
79
 
 
80
 
 
81
 
 
82
Naming
 
83
------
 
84
 
 
85
Functions, methods or members that are in some sense "private" are given
 
86
a leading underscore prefix.  This is just a hint that code outside the
 
87
implementation should probably not use that interface.
 
88
 
 
89
We prefer class names to be concatenated capital words (``TestCase``)
 
90
and variables, methods and functions to be lowercase words joined by
 
91
underscores (``revision_id``, ``get_revision``).
 
92
 
 
93
For the purposes of naming some names are treated as single compound
 
94
words: "filename", "revno".
 
95
 
 
96
Consider naming classes as nouns and functions/methods as verbs.
 
97
 
 
98
 
 
99
Standard names
 
100
--------------
 
101
 
 
102
``revision_id`` not ``rev_id`` or ``revid``
 
103
 
 
104
Functions that transform one thing to another should be named ``x_to_y``
 
105
(not ``x2y`` as occurs in some old code.)
 
106
 
49
107
 
50
108
Writing output
51
109
==============
97
155
You can provide a pattern argument to run a subset. For example, 
98
156
to run just the whitebox tests, run bzr selftest --pattern .*whitebox.*
99
157
 
 
158
 
 
159
Jargon
 
160
======
 
161
 
 
162
revno
 
163
    Integer identifier for a revision on the main line of a branch.
 
164
    Revision 0 is always the null revision; others are 1-based
 
165
    indexes into the branch's revision history.