Mercurial > pylearn

comparison doc/v2_planning/coding_style.txt @ 1181:ae4b4f7654ec

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Updated / closed some points open for debate that were discussed during meeting
author Olivier Delalleau <delallea@iro>
date Fri, 17 Sep 2010 16:41:04 -0400
parents 67f4edabb0cc
children 58a6919d3649
comparison
equal deleted inserted replaced
1180:9ebd40d31a1b 1181:ae4b4f7654ec
12 ---------------------- 12 ----------------------
13 13
14 * File header: 14 * File header:
15 - Do we put the accents in 'Universite de Montreal'? 15 - Do we put the accents in 'Universite de Montreal'?
16 OD: No (restricting code to ASCII characters is much safer) 16 OD: No (restricting code to ASCII characters is much safer)
17
17 - Do we put the Mercurial version number in each file? 18 - Do we put the Mercurial version number in each file?
18 OD: No (useless in my experience, if it's a release the version 19 OD: No (useless in my experience, if it's a release the version
19 number can be provided in the README for instance, and in 20 number can be provided in the README for instance, and in
20 addition Mercurial IDs cannot be easily compared to figure 21 addition Mercurial IDs cannot be easily compared to figure
21 out which of two versions is most recent) 22 out which of two versions is most recent)
22
23 * Avoid contractions in code comments (particularly in
24 documentation): "We do not add blue to red because it does not look good"
25 rather than "We don't add blue to red because it doesn't look good".
26 OD: I mostly find it to be cleaner (been used to it while writing
27 scientific articles too).
28 JB: +1
29
30 * Imperative vs. third-person comments.
31 # Return the sum of elements in x. <-- imperative
32 # Returns the sum of elements in x. <-- third-person
33 OD: I am used to the imperative form and like it better only because it
34 typically saves one letter (the 's') and is easier to conjugate.
35 JB: What about being compatible with markup formats that have a :returns:
36 tag?
37 OD: That'd make sense. However, when I wrote the above I hadn't looked
38 closely at PEP257 yet, and I just noticed the following official
39 recommendation for one-line docstrings in it:
40 The docstring is a phrase ending in a period. It prescribes the
41 function or method's effect as a command ("Do this", "Return that"), not as a
42 description; e.g. don't write "Returns the pathname ...".
43 Anyone knows which style is most popular in the open-source
44 community?
45 23
46 * OD: I like always doing the following when subclassing 24 * OD: I like always doing the following when subclassing
47 a class A: 25 a class A:
48 class B(A): 26 class B(A):
49 def __init__(self, b_arg_1, b_arg_2, **kw): 27 def __init__(self, b_arg_1, b_arg_2, **kw):
59 can benefit from it without modifying their code. 37 can benefit from it without modifying their code.
60 Cons: 38 Cons:
61 - One needs to look at the parent classes to see what these arguments 39 - One needs to look at the parent classes to see what these arguments
62 are. 40 are.
63 - You cannot use a **kw argument in your constructor for your own 41 - You cannot use a **kw argument in your constructor for your own
64 selfish purpose. 42 selfish purpose (well, you can actually, but it would look a bit
43 hackish).
65 - I have no clue whether one could do this with multiple inheritance. 44 - I have no clue whether one could do this with multiple inheritance.
66 - Pb if super class adds an argument that has same name as a child class. 45 - Pb if super class adds an argument that has same name as a child class.
67 Question: Should we encourage this in Pylearn? 46 Question: Should we encourage this in Pylearn?
68
69 JB: +0.5 47 JB: +0.5
48 OD: Was discussed in lab meeting. The feeling was that the last Con was
49 too dangerous. Note however that if we have some system that
50 automatically generates proper doc (i.e. with all arguments, by
51 asking the parent class as well), it could detect the situation
52 mentioned in that last Con (and solve the first one as well).
53
70 54
71 Closed for public debate 55 Closed for public debate
72 ------------------------ 56 ------------------------
57
58 * Imperative vs. third-person comments.
59 # Return the sum of elements in x. <-- imperative
60 # Returns the sum of elements in x. <-- third-person
61 OD: I am used to the imperative form and like it better only because it
62 typically saves one letter (the 's') and is easier to conjugate.
63 JB: What about being compatible with markup formats that have a :returns:
64 tag?
65 OD: That'd make sense. However, when I wrote the above I hadn't looked
66 closely at PEP257 yet, and I just noticed the following official
67 recommendation for one-line docstrings in it:
68 The docstring is a phrase ending in a period. It prescribes the
69 function or method's effect as a command ("Do this", "Return that"), not as a
70 description; e.g. don't write "Returns the pathname ...".
71 Anyone knows which style is most popular in the open-source
72 community?
73 OD: In lab meeting Yoshua ruled out: it is a waste of time to even
74 discuss it. So we let everyone do it the way they like it best.
75
76 * Avoid contractions in code comments (particularly in
77 documentation): "We do not add blue to red because it does not look good"
78 rather than "We don't add blue to red because it doesn't look good".
79 OD: I mostly find it to be cleaner (been used to it while writing
80 scientific articles too).
81 JB: +1
82 OD: Discussed in lab meeting, and agreed on.
73 83
74 * Use imports for packages and modules only. I.e. avoid 84 * Use imports for packages and modules only. I.e. avoid
75 from foo import * 85 from foo import *
76 from foo import Bar 86 from foo import Bar
77 OD: Overall I agree with this. However we probably want to allow some 87 OD: Overall I agree with this. However we probably want to allow some