pylearn: doc/v2_planning/coding

annotate doc/v2_planning/coding_style.txt @ 1133:9baa47482ccc

coding_style: Added a few more coding guidelines for compatibility with various Python versions

author	Olivier Delalleau <delallea@iro>
date	Wed, 15 Sep 2010 15:20:13 -0400
parents	f0a1b88367b0
children	0653a85ff2e8

rev	line source
1009 dc5185cca21e Added files for Coding Style and Optimization committees Olivier Delalleau <delallea@iro> parents: diff changeset	1 Discussion of Coding-Style
dc5185cca21e Added files for Coding Style and Optimization committees Olivier Delalleau <delallea@iro> parents: diff changeset	2 ==========================
dc5185cca21e Added files for Coding Style and Optimization committees Olivier Delalleau <delallea@iro> parents: diff changeset	3
1017 af80b7d182af coding_style: Added list of participants in the committee Olivier Delalleau <delallea@iro> parents: 1009 diff changeset	4 Participants
af80b7d182af coding_style: Added list of participants in the committee Olivier Delalleau <delallea@iro> parents: 1009 diff changeset	5 ------------
af80b7d182af coding_style: Added list of participants in the committee Olivier Delalleau <delallea@iro> parents: 1009 diff changeset	6 - Dumitru
af80b7d182af coding_style: Added list of participants in the committee Olivier Delalleau <delallea@iro> parents: 1009 diff changeset	7 - Fred
af80b7d182af coding_style: Added list of participants in the committee Olivier Delalleau <delallea@iro> parents: 1009 diff changeset	8 - David
1028 c6a74b24330b coding_style: Olivier D confirmed as leader Olivier Delalleau <delallea@iro> parents: 1025 diff changeset	9 - Olivier D [leader]
1017 af80b7d182af coding_style: Added list of participants in the committee Olivier Delalleau <delallea@iro> parents: 1009 diff changeset	10
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	11 Open for public debate
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	12 ----------------------
1072 04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	13
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	14 * Use imports for packages and modules only. I.e. avoid
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	15 from foo import *
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	16 from foo import Bar
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	17 OD: Overall I agree with this. However we probably want to allow some
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	18 exceptions, like:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	19 from itertools import imap, izip
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	20 Also, some people may want to have shortcuts like
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	21 from theano import tensor as T
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	22 but I would prefer to forbid this. It is handy when trying stuff in
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	23 the interactive interpreter, but in real code it can easily get messy
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	24 when you want to copy / paste different pieces of code and they use
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	25 different conventions. Typing tensor.* is a bit longer, but a lot more
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	26 portable.
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	27 JB: I thought that these are nice:
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	28 - "from foo import Bar"
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	29 - "from foo import Bar, Blah"
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	30 What's wrong with them? They keep the code listing short and readable.
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	31 I would discourage these forms when symbols 'Bar' and 'Blah' are
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	32 ambiguous, in which case the parent module prefix serves to disambiguate
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	33 them in the code.
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	34 I agree that the "import A as B" form should be discouraged in general,
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	35 because that's just confusing and makes code less grep-friendly.
1128 03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	36 OD: I agree that "from foo import Bar, Blah" is sometimes convenient
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	37 (typically when you re-use Bar / Blah many times in the same file),
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	38 and would vote in favor of accepting it when it is appropriate.
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	39 This guideline was taken from Google's coding recommendation:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	40 "from foo import * or from foo import Bar is very nasty and can
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	41 lead to serious maintenance issues because it makes it hard to find
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	42 module dependencies."
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	43
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	44 * Imports should usually be on separate lines.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	45 OD: I would add an exception, saying it is ok to group multiple imports
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	46 from the standard library on a single line, e.g.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	47 import os, sys, time
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	48 I just don't see much benefit in putting them on separate lines (for
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	49 third-party imports I agree it is best to keep them separate, as it
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	50 makes dependencies clearer, and diffs look better when someone adds /
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	51 removes an import). Does anyone see a good reason to keep standard
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	52 library imports on different lines?
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	53 JB: what does 'usually' mean here? The guideline seems vacuous.
1128 03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	54 OD: Sorry my fault, I did not quote the whole guideline from PEP8. The
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	55 'usually' was because of what followed:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	56 it's okay to say this though:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	57 from subprocess import Popen, PIPE
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	58 (which btw contradicts Google's recommendation mentioned previously)
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	59
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	60 * The BDFL recommends inserting a blank line between the
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	61 last paragraph in a multi-line docstring and its closing quotes, placing
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	62 the closing quotes on a line by themselves. This way, Emacs'
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	63 fill-paragraph command can be used on it.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	64 OD: I think it is ugly and I have not seen it used much. Any Emacs
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	65 user believes it is a must?
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	66
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	67 * Avoid contractions in code comments (particularly in
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	68 documentation): "We do not add blue to red because it does not look good"
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	69 rather than "We don't add blue to red because it doesn't look good".
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	70 OD: I mostly find it to be cleaner (been used to it while writing
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	71 scientific articles too).
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	72 JB: +1
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	73
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	74 * Imperative vs. third-person comments.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	75 # Return the sum of elements in x. <-- imperative
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	76 # Returns the sum of elements in x. <-- third-person
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	77 OD: I am used to the imperative form and like it better only because it
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	78 typically saves one letter (the 's') and is easier to conjugate.
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	79 JB: What about being compatible with markup formats that have a :returns:
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	80 tag?
1128 03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	81 OD: That'd make sense. However, when I wrote the above I hadn't looked
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	82 closely at PEP257 yet, and I just noticed the following official
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	83 recommendation for one-line docstrings in it:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	84 The docstring is a phrase ending in a period. It prescribes the
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	85 function or method's effect as a command ("Do this", "Return that"), not as a
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	86 description; e.g. don't write "Returns the pathname ...".
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	87 Anyone knows which style is most popular in the open-source
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	88 community?
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	89
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	90 * OD: I like always doing the following when subclassing
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	91 a class A:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	92 class B(A):
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	93 def __init__(self, b_arg_1, b_arg_2, **kw):
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	94 super(B, self).__init__(**kw)
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	95 ...
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	96 The point here is that the constructor always allow for extra keyword
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	97 arguments (except for the class at the very top of the hierarchy), which
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	98 are automatically passed to the parent class.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	99 Pros:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	100 - You do not need to repeat the parent class arguments whenever you
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	101 write a new subclass.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	102 - Whenever you add an argument to the parent class, all child classes
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	103 can benefit from it without modifying their code.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	104 Cons:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	105 - One needs to look at the parent classes to see what these arguments
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	106 are.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	107 - You cannot use a **kw argument in your constructor for your own
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	108 selfish purpose.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	109 - I have no clue whether one could do this with multiple inheritance.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	110 - More?
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	111 Question: Should we encourage this in Pylearn?
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	112
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	113 JB: +0.5
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	114
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	115 * JB: How should we combine capitalization and underscores to name classes
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	116 and functions related to an algorithm like 'SGD' or a model like 'RBM'
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	117 whose common name is capitalized? Case in point: How should I name a
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	118 Hybrid Monte Carlo Sampler? Should I use the common HMC abbreviation?
1128 03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	119 OD: This one is answered by PEP8 (search HTTPServerError in it).
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	120 You should use:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	121 RBMClassName
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	122 rbm_function_name
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	123 As far as using abbreviations is concerned:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	124 All identifiers in the Python standard library (...) SHOULD use
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	125 English words wherever feasible (in many cases, abbreviations and
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	126 technical terms are used which aren't English).
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	127 so I guess HMC is ok when using Hybrid Monte Carlo is considered to
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	128 make some names too long.
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	129
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	130 Note about warnings
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	131 -------------------
1072 04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	132
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	133 Fred: This is a refactored thing from James email of what we should put in message
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	134 that we send to the user:
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	135 1) Hint where in the code this log come from.
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	136 2) Hint how to hide this message? or we should this into documentation.
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	137 3) Tell explicitly if the user can ignore it and the consequence.
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	138
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	139 Existing Python coding style specifications and guidelines
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	140 ----------------------------------------------------------
1017 af80b7d182af coding_style: Added list of participants in the committee Olivier Delalleau <delallea@iro> parents: 1009 diff changeset	141
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	142 * Must-read
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	143 * Official Python coding style guide: http://www.python.org/dev/peps/pep-0008
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	144 * Official docstring conventions: http://www.python.org/dev/peps/pep-0257
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	145 * Google Python Style Guide: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	146 * Interesting
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	147 * Code Like a Pythonista: http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	148 * Can skip
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	149 * Python style for university class: http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	150 * Mailman coding style: http://barry.warsaw.us/software/STYLEGUIDE.txt
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	151 * Some company coding style: http://self.maluke.com/style
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	152 * Chandler coding style: http://chandlerproject.org/Projects/ChandlerCodingStyleGuidelines
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	153 * Outdated recommendations: http://lists.osafoundation.org/pipermail/dev/2003-March/000479.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	154 * Mostly some beginners tips: http://learnpython.pbworks.com/PythonTricks
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	155 * More beginners tips: http://eikke.com/how-not-to-write-python-code/
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	156 * Cogent coding guidelines: http://jaynes.colorado.edu/PythonGuidelines.html
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	157 * Djangoo coding guidelines: http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	158 * Numpy documentation style guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	159 * Some random guy guidelines (nothing special): http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
1009 dc5185cca21e Added files for Coding Style and Optimization committees Olivier Delalleau <delallea@iro> parents: diff changeset	160
1020 53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	161 We will probably want to take PEP-8 as starting point, and read what other
53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	162 people think about it / how other coding guidelines differ from it.
53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	163
1050 573363a9b5c7 more tools Dumitru Erhan <dumitru.erhan@gmail.com> parents: 1049 diff changeset	164 Dumi: we should also try to find tools that automate these
573363a9b5c7 more tools Dumitru Erhan <dumitru.erhan@gmail.com> parents: 1049 diff changeset	165 processes: pylint, pyflakes, pychecker, pythontidy
1049 ff9361e39c97 remark on fiding tools Dumitru Erhan <dumitru.erhan@gmail.com> parents: 1033 diff changeset	166
1060 b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	167 OD: Things about PEP 8 I don't like (but it may be just me):
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	168
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	169 * If necessary, you can add an extra pair of parentheses around an
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	170 expression, but sometimes using a backslash looks better.
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	171 --> I rarely find that backslash looks better. In most situations you can
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	172 get rid of them. Typically I prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	173 if (cond_1 and
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	174 cond_2 and
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	175 cond_3):
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	176 to
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	177 if cond_1 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	178 cond_2 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	179 cond_3:
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	180
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	181 * You should use two spaces after a sentence-ending period.
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	182 --> Looks weird to me.
1063 074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	183 (DWF: This is an old convention from the typewriter era. It has more
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	184 or less been wiped out by HTML's convention of ignoring extra
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	185 whitespace: see http://en.wikipedia.org/wiki/Sentence_spacing for
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	186 more detail. I think it's okay to drop this convention in source code.)
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	187 OD: Cool, thanks, I guess we can drop it then.
1060 b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	188
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	189 * Missing in PEP 8:
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	190 - How to indent multi-line statements? E.g. do we want
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	191 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	192 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	193 or
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	194 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	195 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	196 or
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	197 x = my_func(
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	198 a, b, c, d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	199 --> Probably depends on the specific situation, but we could have a
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	200 few typical examples (and the same happens with multi-lines lists)
1072 04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	201 (Fred: I would do 2 or 3, but not 1. I find it more redable when the
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	202 indent is broken after a paranthesis then at any point.
1075 d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	203 OD: After thinking about it, I agreee as well. My recommendation would
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	204 be to go with 2 when it can fit on two lines, and 3 otherwise. Same
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	205 with lists.
1060 b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	206
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	207 Documentation
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	208 -------------
1020 53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	209
53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	210 How do we write doc?
53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	211
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	212 Compatibility with various Python versions
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	213 ------------------------------------------
1020 53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	214
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	215 * Which Python 2.x version do we want to support?
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	216
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	217 * Is it reasonable to have coding guidelines that would make the code as
1020 53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	218 compatible as possible with Python 3?
53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	219
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	220 C coding style
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	221 --------------
1022 e21b3fdec4ef add comments. Frederic Bastien <nouiz@nouiz.org> parents: 1020 diff changeset	222
e21b3fdec4ef add comments. Frederic Bastien <nouiz@nouiz.org> parents: 1020 diff changeset	223 We also need a c-style coding style.
1033 f1e0a180574a coding_style: Added meeting date & time Olivier Delalleau <delallea@iro> parents: 1028 diff changeset	224
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	225 Meeting 2010/09/09
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	226 ------------------
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	227
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	228 * Coding guidelines
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	229 PEP 8 & Google should be a good basis to start with.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	230 Task: Highlight the most important points in them (OD).
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	231
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	232 * Documentation
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	233 Use RST with Sphinx.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	234 Task: Provide specific examples on how to document a class, method, and some
1072 04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	235 specific classes like Op (DE). Modify the theano documentation to include that.
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	236 OD: May want to check out
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	237 http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	238
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	239 * Python versions to be supported
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	240 Support 2.4 (because some of the clusters are still running 2.4) and write
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	241 code that can be converted to 3.x with 2to3 in a straightforward way.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	242 Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD)
1063 074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	243 (DWF: Pauli Virtanen and others have put together extensive
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	244 documentation in the process of porting NumPy to Py3K, see his notes at
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	245 http://projects.scipy.org/numpy/browser/trunk/doc/Py3K.txt -- this is
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	246 the most complete resource for complicated combinations of Python and C).
074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	247
1033 f1e0a180574a coding_style: Added meeting date & time Olivier Delalleau <delallea@iro> parents: 1028 diff changeset	248
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	249 * C coding style
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	250 How to write C code (in particular for Numpy / Cuda), and how to mix C and
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	251 Python.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	252 Task: See if there would be a sensible C code style to follow (maybe look how
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	253 Numpy does it), and how projects that mix C and Python deal with it (e.g. use
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	254 separate files, or be able to have mixed syntax highlighting?) (FB)
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	255
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	256 * Program output
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	257 Use the warning and logging modules. Avoid print as much as possible.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	258 Task: Look into these modules to define general guidelines e.g. to decide when
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	259 to use warning instead of logging. (DWF)
1033 f1e0a180574a coding_style: Added meeting date & time Olivier Delalleau <delallea@iro> parents: 1028 diff changeset	260
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	261 * Automatized code verification
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	262 Use pychecker & friends to make sure everything is fine.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	263 Task: Look into the various options available (DE)
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	264
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	265 * Tests
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	266 Force people to write tests. Automatic email reminder of code lines not
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	267 covered by tests (see if we can get this from nosetests). Decorator to mark
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	268 some classes / methods as not being tested yet, so as to be able to
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	269 automatically warn the user when he is using untested stuff (and to remind
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	270 ourselves we should add a test).
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	271 Task: See feasibility. (OD)
1132 f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	272 Result: See section 'Enforcing strict testing policy'.
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	273
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	274 * VIM / Emacs plugins / config files
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	275 To enforce good coding style automatically.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	276 Task: Look for existing options. (FB)
1063 074901ccf7b6 Some additional notes on some of the tasks and points from the meeting. wardefar@grincheux.iro.umontreal.ca parents: 1062 diff changeset	277 (DWF: I have put some time into this for vim, I will send around my files)
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	278
1066 e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	279 Suggestion by PV
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	280 ----------------
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	281
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	282 Have a sample code that showcases everything one should comply to.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	283
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	284 Some coding guidelines (work-in-progress from OD)
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	285 -------------------------------------------------
1066 e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	286
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	287 * Avoid using lists if all you care about is iterating on something. Using
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	288 lists:
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	289 - uses more memory (and possibly more CPU if the code may break out of
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	290 the iteration)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	291 - can lead to ugly code when converted to Python 3 with 2to3
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	292 - can have a different behavior if evaluating elements in the list has
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	293 side effects (if you want these side effects, make it explicit by
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	294 assigning the list to some variable before iterating on it)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	295
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	296 Iterative version List version
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	297 my_dict.iterkeys() my_dict.keys()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	298 my_dict.itervalues() my_dict.values()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	299 my_dict.iteritems() my_dict.items()
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	300 itertools.imap map
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	301 itertools.ifilter filter
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	302 itertools.izip zip
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	303 xrange range
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	304
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	305 * Use `in` on container objects instead of using class-specific methods.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	306 It is easier to read and may allow you to use your code with different
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	307 container types.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	308
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	309 Yes No
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	310 --- --
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	311 key in my_dict my_dict.has_key(key)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	312 sub_string in my_string my_string.find(sub_string) >= 0
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	313
1073 3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	314
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	315 * Generally prefer list comprehensions to map / filter, as the former are
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	316 easier to read.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	317 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	318 non_comments = [line.strip() for line in my_file.readlines()
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	319 if not line.startswith('#')]
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	320 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	321 non_comments = map(str.strip,
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	322 filter(lambda line: not line.startswith('#'),
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	323 my_file.readlines()))
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	324
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	325 * Use the `key` argument instead of `cmp` when sorting (for Python 3
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	326 compatibility).
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	327 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	328 my_list.sort(key=abs)
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	329 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	330 my_list.sort(cmp=lambda x, y: cmp(abs(x), abs(y)))
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	331
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	332 * Use // for integer division (for readability and Python 3 compatibility).
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	333 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	334 n_samples_per_split = n_samples // n_splits
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	335 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	336 n_samples_per_split = n_samples / n_splits
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	337
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	338 * Only use ASCII characters in code files.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	339
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	340 * Code indent must be done with four blank characters (not with tabs).
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	341
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	342 * Limit lines to 79 characters.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	343
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	344 * Comments should start with a capital letter (unless the first word is a
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	345 code identifier) and end with a period (very short inline comments may
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	346 ignore this rule).
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	347
1073 3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	348 * Whenever you read / write binary files, specify it in the mode ('rb' for
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	349 reading, 'wb' for writing). This is important for cross-platform and
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	350 Python 3 compatibility (e.g. when pickling / unpickling objects).
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	351
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	352 * Avoid tuple parameter unpacking to avoid very ugly code when converting
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	353 to Python 3.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	354 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	355 def f(x, y_z):
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	356 y, z = y_z
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	357 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	358 def f(x, (y, z))
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	359
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	360 * Only use cPickle, not pickle.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	361
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	362 * Always raise exception with
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	363 raise MyException(args)
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	364 where MyException inherits from Exception.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	365
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	366 * Imports should be listed in alphabetical order. It makes it easier to
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	367 verify that something is imported, and avoids duplicated imports.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	368
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	369 * Use absolute imports only. This is compatible across a wider range of
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	370 Python versions, and avoids confusion about what is being
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	371 imported.
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	372
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	373 * Use a leading underscore '_' for internal attributes / methods,
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	374 but avoid the double underscore '__' unless you know what you are
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	375 doing.
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	376
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	377 * A script's only top-level code should be something like:
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	378 if __name__ == '__main__':
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	379 sys.exit(main())
56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	380
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	381 * No conditional expression (not supported in Python 2.4). These are
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	382 expressions of the form
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	383 x = y if condition else z
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	384
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	385 * Use either "try ... except" or "try ... finally", but do not mix
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	386 "except" with "finally" (which is not supported in Python 2.4).
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	387
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	388 * Do not use the `any` and `all` builtin functions (they are not supported
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	389 in Python 2.4).
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	390
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	391 * Do not use the `hashlib` module (not supported in Python 2.4).
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	392
1075 d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	393 Mercurial commits
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	394 -----------------
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	395
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	396 * How to write good commit messages?
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	397 OD: Check Django's guidelines (link above)
1075 d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	398 * Standardize the merge commit text (what is the message from fetch?)
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	399
1123 1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	400 Type checking
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	401 -------------
1103 56c5f0990869 coding_style: More work on some guidelines, also put some points to debate in a specific section Olivier Delalleau <delallea@iro> parents: 1075 diff changeset	402
1123 1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	403 (Suggested by Francois Savard)
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	404
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	405 vu que vous êtes en train de vous occuper de l'aspect coding style, je
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	406 mentionne ceci, à faire ce que vous en voulez: j'aime bien éviter des
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	407 erreurs sur l'ordre de mes paramètres, sur les assumptions sur les
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	408 paramètres etc. en faisant des argument check. Ça remplace un peu le
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	409 static type checking des langages genre Java.
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	410
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	411 En Python y'a une façon élégante de définir ses propres typecheckers,
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	412 value checkers etc. et ensuite les passer en paramètre à un décorateur de
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	413 fonction:
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	414
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	415 http://code.activestate.com/recipes/454322-type-checking-decorator/
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	416
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	417 (Juste un exemple, vu que les checks peuvent être plus élaborés, inclure
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	418 des value checks (>0 etc.), être flexibles pour ne pas demander que ce
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	419 soit un type fixe mais plutôt que ça réponde à certaines contraintes (que
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	420 ça "ressemble" à un float, p. ex.). J'avais développé une lib pour faire
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	421 qqch du genre en Javascript).
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	422
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	423 Je ne sais pas si vous comptiez parler de ça, et si ça vaut la peine, mais
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	424 personnellement je préfère du code à des commentaires qui peuvent être out
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	425 of sync avec le contenu d'une méthode. Si vous croyez que ça vaut la peine,
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	426 vous pourriez p-e définir des type/value-checkers standards pour éviter que
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	427 tout le monde redéfinissent les siens à sa façon.
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	428
1130 aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	429 Consistent inf / nan
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	430 --------------------
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	431
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	432 OD: Use numpy.inf and numpy.nan rather than float('inf') / float('nan')?
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	433 (should be slightly more efficient even if efficiency usually doesn't matter
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	434 here - the main goal would be for everyone to use the same inf / nan to make
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	435 the code consistent).
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	436
1132 f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	437 Enforcing strict testing policy
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	438 -------------------------------
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	439
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	440 The `coverage` third-party module provides a way to gather code coverage
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	441 statistics in the test suite. `nosetests` has a plugin that can be activated
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	442 with the --with-coverage option to use this module.
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	443 It is possible to know which lines specifically lack coverage. However, we
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	444 will probably want to post-process this data to do more than a simple report
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	445 (which noone will care about). This could be done either by parsing nosetests'
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	446 coverage output, or modifying its coverage plugin, or writing our own version
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	447 of it. The main goal would be to identify who is responsible for writing lines
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	448 that are not currently covered (using 'hg annotate'), in order to send email
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	449 notifications.
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	450
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	451 We should aim at 100% code coverage in tests. This is realistic because
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	452 `coverage` offers ways to ignore coverage for lines we explicitely do not want
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	453 to cover (typically debug code, or AssertionError / NotImplementedError that
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	454 are not supposed to be triggered during normal usage).
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	455 We may need to do some advanced processing though to e.g. collect results from
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	456 multiple build bots, if for instance some bot is running tests without GPU
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	457 support, and another one is taking care of the GPU tests.
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	458
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	459 Code that should be tested but for which no test is currently written would
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	460 also require some decorator / helper function that would trigger a warning at
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	461 run-time (only once / execution). This could be enforced by adopting a
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	462 different policy about lack-of-coverage notification emails, depending on
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	463 whether or not the warning is present:
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	464 - if there is no warning, daily email notification (ADD A WARNING!!!)
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	465 - if there is a warning, weekly email notification (ADD A TEST!!!)
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	466

Mercurial > pylearn

annotate doc/v2_planning/coding_style.txt @ 1133:9baa47482ccc