~bzr-pqm/bzr/bzr.dev : revision 1417

1

============================

2

guidelines for modifying bzr

2

Guidelines for modifying bzr

3

============================

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

23

31

function runs. Import statements have a cost, so try to make sure

24

32

they don't run inside hot functions.

25

33

26

* Please write PEP-8__ compliant code.

27

28

One often-missed requirement is that the first line of docstrings

29

should be a self-contained one-sentence summary.

30

31

__ http://www.python.org/peps/pep-0008.html

32

33

34

* Module names should always be given fully-qualified,

34

35

i.e. ``bzrlib.hashcache`` not just ``hashcache``.

35

36

* If you change the behaviour of an API in an incompatible way, please

37

be sure to change its name as well. For instance, if I add a keyword

38

parameter to branch.commit - thats fine. On the other hand, if I add

39

a keyword parameter to branch.commit which is a *required* transaction

40

object, I should rename the api - i.e. to 'branch.commit_transaction'.

41

This will prevent users of the old api outside of the tree getting

42

surprising results.

43

Instead, they will get an Attribute error as the api is missing, and

44

will know to update their code. If in doubt, just ask on #bzr.

45

37

Evolving interfaces

38

-------------------

39

40

If you change the behaviour of an API in an incompatible way, please

41

be sure to change its name as well. For instance, if I add a keyword

42

parameter to branch.commit - that's fine. On the other hand, if I add

43

a keyword parameter to branch.commit which is a *required* transaction

44

object, I should rename the api - i.e. to 'branch.commit_transaction'.

45

46

This will prevent users of the old api getting surprising results.

47

Instead, they will get an Attribute error as the api is missing, and

48

will know to update their code. If in doubt, just ask on #bzr.

46

49

47

50

Documentation

48

51

=============

58

61

should be done.

59

62

60

63

64

API documentation

65

-----------------

66

67

Functions, methods, classes and modules should have docstrings

68

describing how they are used.

69

70

The first line of the docstring should be a self-contained sentence.

71

72

For the special case of Command classes, this acts as the user-visible

73

documentation shown by the help command.

74

75

The docstrings should be formatted as reStructuredText_ (like this

76

document), suitable for processing using the epydoc_ tool into HTML

77

documentation.

78

79

.. _reStructuredText: http://docutils.sourceforge.net/rst.html

80

.. _epydoc: http://epydoc.sourceforge.net/

81

82

83

84

Coding style

85

============

86

87

Please write PEP-8__ compliant code.

88

89

One often-missed requirement is that the first line of docstrings

90

should be a self-contained one-sentence summary.

91

92

__ http://www.python.org/peps/pep-0008.html

93

94

95

96

Naming

97

------

98

99

Functions, methods or members that are in some sense "private" are given

100

a leading underscore prefix. This is just a hint that code outside the

101

implementation should probably not use that interface.

102

103

We prefer class names to be concatenated capital words (``TestCase``)

104

and variables, methods and functions to be lowercase words joined by

105

underscores (``revision_id``, ``get_revision``).

106

107

For the purposes of naming some names are treated as single compound

108

words: "filename", "revno".

109

110

Consider naming classes as nouns and functions/methods as verbs.

111

112

113

Standard names

114

--------------

115

116

``revision_id`` not ``rev_id`` or ``revid``

117

118

Functions that transform one thing to another should be named ``x_to_y``

119

(not ``x2y`` as occurs in some old code.)

120

61

121

62

122

Writing output

63

123

==============

109

169

You can provide a pattern argument to run a subset. For example,

110

170

to run just the whitebox tests, run bzr selftest --pattern .*whitebox.*

111

171

172

173

Jargon

174

======

175

176

revno

177

Integer identifier for a revision on the main line of a branch.

178

Revision 0 is always the null revision; others are 1-based

179

indexes into the branch's revision history.