1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
Coding conventions for PyBaz
Editor: David Allouche <david@allouche.net>
* Introduction
Good code must look good. You can recognize bad code from its shape.
Pretty code is enjoyable to read, edit and debug. Pretty code is easy
to process by automated tools.
While all those statements may not always be true, please just suspend
your disbelief :-)
Code that does not conform to the following style rules will be edited
at some point to make it conformant. That is the kind of change which
can cause needless merge conflicts, thus causing us all displeasure.
Some of the code I have written may not conform to these
recommandations, generally it should be fixed.
* Bazaar Usage
Bazaar is the versioning system used for the development of PyBaz,
that is only fair since PyBaz implements Python bindings for Bazaar.
All source files must use taglines. New files should use taglines
generated by the uuidgen program. Taglines containing english text
(like a short descrition of the file) are forbidden.
Pure text files which may be printed (like this one or the README
file) can use explicit ids.
* Pychecker
All source files must be valided using PyChecker. The check.py script
sets the appropriate suppressions and load all modules.
To override any suppressions defined in "~/.pycheckrc", check.py sets
HOME to the current directory, which is expected to be within the
pybaz source tree. That means you should not run check.py from within
your home directory. (If you have a better way to do that, you are
welcome).
* General Conventions
The base for the PyBaz coding conventions are the following PEP
documents:
PEP 8 -- Style Guide for Python Code
http://www.python.org/peps/pep-0008.html
PEP 257 -- Docstring Convention
http://www.python.org/peps/pep-0257.html
You should start by reading those references. This document will only
describe differences from the conventions described in these
documents and repeat a few important conventions.
* Naming Conventions
Class names must use MixedCase.
As an exception, iterator classes must be named as functions because
they are used in the same way as functions returning a sequence.
Function and method names must use lowercase_with_underscore for long
names (e.g. exec_safe_status_stdout). Lowercase without separator
_may_ be used for short names. When in doubt, use underscore separated
names.
Variable names obey the same naming conventions as function and method
names. One letter variables are allowed when the variable is only used
very locally.
Never use the characters `l' (lowercase letter el), `O' (uppercase
letter oh), or `I' (uppercase letter eye) as single character variable
names. In some fonts, these characters are indistinguisable from the
numerals one and zero. When tempted to use `l' use `L' instead.
* Text width
The text must fit in 79 columns. If it makes it look better, it may be
wrapped on fewer columns (e.g. 70).
The first line of "class" and "def" statement must fit in 76 columns,
so emacs outline mode has room for an ellipsis.
* Whitespace
Separate top-level function and class definitions with two blank
lines.
Method definitions inside a class are separated by a single blank
line. Extra blank lines may be used (sparingly) to separate groups of
related functions. Blank lines may be omitted between related
one-liners.
When blank lines are used to separate method definitions, there is
also a blank line between the `class' line and the first method
definition.
Class statements defining a property may be placed immediately after
the methods used by the property, without intervening blank lines.
|
