Show More
@@ -1,78 +1,112 b'' | |||||
1 | ============ |
|
1 | ============ | |
2 | Coding guide |
|
2 | Coding guide | |
3 | ============ |
|
3 | ============ | |
4 |
|
4 | |||
5 | General coding conventions |
|
5 | General coding conventions | |
6 | ========================== |
|
6 | ========================== | |
7 |
|
7 | |||
8 | In general, we'll try to follow the standard Python style conventions as |
|
8 | In general, we'll try to follow the standard Python style conventions as | |
9 | described in Python's PEP 8 [PEP8]_, the official Python Style Guide. |
|
9 | described in Python's PEP 8 [PEP8]_, the official Python Style Guide. | |
10 |
|
10 | |||
11 | Other general comments: |
|
11 | Other general comments: | |
12 |
|
12 | |||
13 | * In a large file, top level classes and functions should be separated by 2 |
|
13 | * In a large file, top level classes and functions should be separated by 2 | |
14 | lines to make it easier to separate them visually. |
|
14 | lines to make it easier to separate them visually. | |
15 |
|
15 | |||
16 | * Use 4 spaces for indentation, **never** use hard tabs. |
|
16 | * Use 4 spaces for indentation, **never** use hard tabs. | |
17 |
|
17 | |||
18 | * Keep the ordering of methods the same in classes that have the same methods. |
|
18 | * Keep the ordering of methods the same in classes that have the same methods. | |
19 | This is particularly true for classes that implement similar interfaces and |
|
19 | This is particularly true for classes that implement similar interfaces and | |
20 | for interfaces that are similar. |
|
20 | for interfaces that are similar. | |
21 |
|
21 | |||
22 | Naming conventions |
|
22 | Naming conventions | |
23 | ================== |
|
23 | ================== | |
24 |
|
24 | |||
25 | In terms of naming conventions, we'll follow the guidelines of PEP 8 [PEP8]_. |
|
25 | In terms of naming conventions, we'll follow the guidelines of PEP 8 [PEP8]_. | |
26 | Some of the existing code doesn't honor this perfectly, but for all new |
|
26 | Some of the existing code doesn't honor this perfectly, but for all new | |
27 | IPython code (and much existing code is being refactored), we'll use: |
|
27 | IPython code (and much existing code is being refactored), we'll use: | |
28 |
|
28 | |||
29 | * All ``lowercase`` module names. |
|
29 | * All ``lowercase`` module names. | |
30 |
|
30 | |||
31 | * ``CamelCase`` for class names. |
|
31 | * ``CamelCase`` for class names. | |
32 |
|
32 | |||
33 | * ``lowercase_with_underscores`` for methods, functions, variables and |
|
33 | * ``lowercase_with_underscores`` for methods, functions, variables and | |
34 | attributes. |
|
34 | attributes. | |
35 |
|
35 | |||
36 | This may be confusing as some of the existing codebase uses a different |
|
36 | This may be confusing as some of the existing codebase uses a different | |
37 | convention (``lowerCamelCase`` for methods and attributes). Slowly, we will |
|
37 | convention (``lowerCamelCase`` for methods and attributes). Slowly, we will | |
38 | move IPython over to the new convention, providing shadow names for backward |
|
38 | move IPython over to the new convention, providing shadow names for backward | |
39 | compatibility in public interfaces. |
|
39 | compatibility in public interfaces. | |
40 |
|
40 | |||
41 | There are, however, some important exceptions to these rules. In some cases, |
|
41 | There are, however, some important exceptions to these rules. In some cases, | |
42 | IPython code will interface with packages (Twisted, Wx, Qt) that use other |
|
42 | IPython code will interface with packages (Twisted, Wx, Qt) that use other | |
43 | conventions. At some level this makes it impossible to adhere to our own |
|
43 | conventions. At some level this makes it impossible to adhere to our own | |
44 | standards at all times. In particular, when subclassing classes that use other |
|
44 | standards at all times. In particular, when subclassing classes that use other | |
45 | naming conventions, you must follow their naming conventions. To deal with |
|
45 | naming conventions, you must follow their naming conventions. To deal with | |
46 | cases like this, we propose the following policy: |
|
46 | cases like this, we propose the following policy: | |
47 |
|
47 | |||
48 | * If you are subclassing a class that uses different conventions, use its |
|
48 | * If you are subclassing a class that uses different conventions, use its | |
49 | naming conventions throughout your subclass. Thus, if you are creating a |
|
49 | naming conventions throughout your subclass. Thus, if you are creating a | |
50 | Twisted Protocol class, used Twisted's |
|
50 | Twisted Protocol class, used Twisted's | |
51 | ``namingSchemeForMethodsAndAttributes.`` |
|
51 | ``namingSchemeForMethodsAndAttributes.`` | |
52 |
|
52 | |||
53 | * All IPython's official interfaces should use our conventions. In some cases |
|
53 | * All IPython's official interfaces should use our conventions. In some cases | |
54 | this will mean that you need to provide shadow names (first implement |
|
54 | this will mean that you need to provide shadow names (first implement | |
55 | ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all |
|
55 | ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all | |
56 | costs, but it will probably be necessary at times. But, please use this |
|
56 | costs, but it will probably be necessary at times. But, please use this | |
57 | sparingly! |
|
57 | sparingly! | |
58 |
|
58 | |||
59 | Implementation-specific *private* methods will use |
|
59 | Implementation-specific *private* methods will use | |
60 | ``_single_underscore_prefix``. Names with a leading double underscore will |
|
60 | ``_single_underscore_prefix``. Names with a leading double underscore will | |
61 | *only* be used in special cases, as they makes subclassing difficult (such |
|
61 | *only* be used in special cases, as they makes subclassing difficult (such | |
62 | names are not easily seen by child classes). |
|
62 | names are not easily seen by child classes). | |
63 |
|
63 | |||
64 | Occasionally some run-in lowercase names are used, but mostly for very short |
|
64 | Occasionally some run-in lowercase names are used, but mostly for very short | |
65 | names or where we are implementing methods very similar to existing ones in a |
|
65 | names or where we are implementing methods very similar to existing ones in a | |
66 | base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had |
|
66 | base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had | |
67 | established precedent). |
|
67 | established precedent). | |
68 |
|
68 | |||
69 | The old IPython codebase has a big mix of classes and modules prefixed with an |
|
69 | The old IPython codebase has a big mix of classes and modules prefixed with an | |
70 | explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned |
|
70 | explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned | |
71 | upon, as namespaces offer cleaner prefixing. The only case where this approach |
|
71 | upon, as namespaces offer cleaner prefixing. The only case where this approach | |
72 | is justified is for classes which are expected to be imported into external |
|
72 | is justified is for classes which are expected to be imported into external | |
73 | namespaces and a very generic name (like Shell) is too likely to clash with |
|
73 | namespaces and a very generic name (like Shell) is too likely to clash with | |
74 | something else. However, if a prefix seems absolutely necessary the more |
|
74 | something else. However, if a prefix seems absolutely necessary the more | |
75 | specific ``IPY`` or ``ipy`` are preferred. |
|
75 | specific ``IPY`` or ``ipy`` are preferred. | |
76 |
|
76 | |||
77 | .. [PEP8] Python Enhancement Proposal 8. http://www.python.org/peps/pep-0008.html |
|
77 | .. [PEP8] Python Enhancement Proposal 8. http://www.python.org/peps/pep-0008.html | |
78 |
|
78 | |||
|
79 | Attribute declarations for objects | |||
|
80 | ================================== | |||
|
81 | ||||
|
82 | In general, objects should declare in their *class* all attributes the object | |||
|
83 | is meant to hold throughout its life. While Python allows you to add an | |||
|
84 | attribute to an instance at any point in time, this makes the code harder to | |||
|
85 | read and requires methods to constantly use checks with hasattr() or try/except | |||
|
86 | calls. By declaring all attributes of the object in the class header, there is | |||
|
87 | a single place one can refer to for understanding the object's data interface, | |||
|
88 | where comments can explain the role of each variable and when possible, | |||
|
89 | sensible deafaults can be assigned. | |||
|
90 | ||||
|
91 | .. Warning:: | |||
|
92 | ||||
|
93 | If an attribute is meant to contain a mutable object, it should be set to | |||
|
94 | ``None`` in the class and its mutable value should be set in the object's | |||
|
95 | constructor. Since class attributes are shared by all instances, failure | |||
|
96 | to do this can lead to difficult to track bugs. But you should still set | |||
|
97 | it in the class declaration so the interface specification is complete and | |||
|
98 | documdented in one place. | |||
|
99 | ||||
|
100 | A simple example:: | |||
|
101 | ||||
|
102 | class foo: | |||
|
103 | # X does..., sensible default given: | |||
|
104 | x = 1 | |||
|
105 | # y does..., default will be set by constructor | |||
|
106 | y = None | |||
|
107 | # z starts as an empty list, must be set in constructor | |||
|
108 | z = None | |||
|
109 | ||||
|
110 | def __init__(self, y): | |||
|
111 | self.y = y | |||
|
112 | self.z = [] |
General Comments 0
You need to be logged in to leave comments.
Login now