pylearn: doc/v2_planning/coding

annotate doc/v2_planning/coding_style.txt @ 1144:1679742e7aa1

Writing related to the tasks assigned to me at today's meeting.

author	David Warde-Farley <wardefar@iro.umontreal.ca>
date	Thu, 16 Sep 2010 16:10:10 -0400
parents	6c79394b6b20
children	f6011a2aff0b

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 * 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	15 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	16 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	17 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	18 scientific articles too).
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	19 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	20
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 * 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	22 # 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	23 # 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	24 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	25 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	26 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	27 tag?
1128 03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	28 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	29 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	30 recommendation for one-line docstrings in it:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	31 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	32 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	33 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	34 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	35 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	36
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	37 * 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	38 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	39 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	40 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	41 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	42 ...
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 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	44 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	45 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	46 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	47 - 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	48 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	49 - 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	50 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	51 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	52 - 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	53 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	54 - 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	55 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	56 - 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	57 - 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	58 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	59
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	60 JB: +0.5
60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	61
1140 7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	62 Closed for public debate
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	63 ------------------------
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	64
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	65 * Use imports for packages and modules only. I.e. avoid
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	66 from foo import *
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	67 from foo import Bar
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	68 OD: Overall I agree with this. However we probably want to allow some
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	69 exceptions, like:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	70 from itertools import imap, izip
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	71 Also, some people may want to have shortcuts like
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	72 from theano import tensor as T
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	73 but I would prefer to forbid this. It is handy when trying stuff in
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	74 the interactive interpreter, but in real code it can easily get messy
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	75 when you want to copy / paste different pieces of code and they use
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	76 different conventions. Typing tensor.* is a bit longer, but a lot more
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	77 portable.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	78 JB: I thought that these are nice:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	79 - "from foo import Bar"
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	80 - "from foo import Bar, Blah"
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	81 What's wrong with them? They keep the code listing short and readable.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	82 I would discourage these forms when symbols 'Bar' and 'Blah' are
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	83 ambiguous, in which case the parent module prefix serves to disambiguate
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	84 them in the code.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	85 I agree that the "import A as B" form should be discouraged in general,
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	86 because that's just confusing and makes code less grep-friendly.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	87 OD: I agree that "from foo import Bar, Blah" is sometimes convenient
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	88 (typically when you re-use Bar / Blah many times in the same file),
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	89 and would vote in favor of accepting it when it is appropriate.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	90 This guideline was taken from Google's coding recommendation:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	91 "from foo import * or from foo import Bar is very nasty and can
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	92 lead to serious maintenance issues because it makes it hard to find
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	93 module dependencies."
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	94 OD: Decision was taken in committee's meeting to allow
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	95 from foo import Bar, Blah
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	96 when imported stuff is re-used multiple times in the same file, and
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	97 there is no ambiguity.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	98
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	99 * Imports should usually be on separate lines.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	100 OD: I would add an exception, saying it is ok to group multiple imports
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	101 from the standard library on a single line, e.g.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	102 import os, sys, time
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	103 I just don't see much benefit in putting them on separate lines (for
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	104 third-party imports I agree it is best to keep them separate, as it
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	105 makes dependencies clearer, and diffs look better when someone adds /
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	106 removes an import). Does anyone see a good reason to keep standard
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	107 library imports on different lines?
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	108 JB: what does 'usually' mean here? The guideline seems vacuous.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	109 OD: Sorry my fault, I did not quote the whole guideline from PEP8. The
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	110 'usually' was because of what followed:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	111 it's okay to say this though:
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	112 from subprocess import Popen, PIPE
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	113 (which btw contradicts Google's recommendation mentioned previously)
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	114 OD: Decision was taken in committee's meeting to allow multiple imports
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	115 on the same line for standard library modules (only).
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	116
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	117 * The BDFL recommends inserting a blank line between the
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	118 last paragraph in a multi-line docstring and its closing quotes, placing
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	119 the closing quotes on a line by themselves. This way, Emacs'
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	120 fill-paragraph command can be used on it.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	121 OD: I think it is ugly and I have not seen it used much. Any Emacs
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	122 user believes it is a must?
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	123 OD: Decision was taken in committee's meeting to drop this
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	124 recommendation.
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	125
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	126 * 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	127 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	128 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	129 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	130 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	131 You should use:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	132 RBMClassName
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	133 rbm_function_name
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	134 As far as using abbreviations is concerned:
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	135 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	136 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	137 technical terms are used which aren't English).
03b41a79bd60 coding_style: Replies to James' questions / comments Olivier Delalleau <delallea@iro> parents: 1123 diff changeset	138 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	139 make some names too long.
1113 60ef81fe1825 2cents in coding_style James Bergstra <bergstrj@iro.umontreal.ca> parents: 1103 diff changeset	140
1140 7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 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 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	143 -------------------
1072 04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	144
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	145 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	146 that we send to the user:
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	147 1) Hint where in the code this log come from.
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	148 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	149 3) Tell explicitly if the user can ignore it and the consequence.
04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	150
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	151 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	152 ----------------------------------------------------------
1017 af80b7d182af coding_style: Added list of participants in the committee Olivier Delalleau <delallea@iro> parents: 1009 diff changeset	153
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	154 * 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	155 * 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	156 * 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	157 * 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	158 * 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	159 * Code Like a Pythonista: http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
1134 0653a85ff2e8 coding_style: Moved url about Numpy conversion to Python 3 to the url list Olivier Delalleau <delallea@iro> parents: 1133 diff changeset	160 * Numpy notes on conversion to Python 3: http://projects.scipy.org/numpy/browser/trunk/doc/Py3K.txt
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	161 * 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	162 * 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	163 * 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	164 * 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	165 * 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	166 * 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	167 * 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	168 * 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	169 * 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	170 * 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	171 * 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	172 * 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	173
1020 53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	174 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	175 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	176
1050 573363a9b5c7 more tools Dumitru Erhan <dumitru.erhan@gmail.com> parents: 1049 diff changeset	177 Dumi: we should also try to find tools that automate these
573363a9b5c7 more tools Dumitru Erhan <dumitru.erhan@gmail.com> parents: 1049 diff changeset	178 processes: pylint, pyflakes, pychecker, pythontidy
1049 ff9361e39c97 remark on fiding tools Dumitru Erhan <dumitru.erhan@gmail.com> parents: 1033 diff changeset	179
1060 b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	180 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	181
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	182 * 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	183 expression, but sometimes using a backslash looks better.
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	184 --> 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	185 get rid of them. Typically I prefer:
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	186 if (cond_1 and
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	187 cond_2 and
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	188 cond_3):
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	189 to
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	190 if cond_1 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	191 cond_2 and \
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	192 cond_3:
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	193
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	194 * 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	195 --> 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	196 (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	197 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	198 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	199 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	200 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	201
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	202 * Missing in PEP 8:
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	203 - 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	204 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	205 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	206 or
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	207 x = my_func(a, b, c,
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	208 d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	209 or
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	210 x = my_func(
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	211 a, b, c, d, e, f)
b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 diff changeset	212 --> 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	213 few typical examples (and the same happens with multi-lines lists)
1072 04bbf05d249c small comment. Frederic Bastien <nouiz@nouiz.org> parents: 1070 diff changeset	214 (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	215 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	216 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	217 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	218 with lists.
1060 b4ccf6b43f27 coding_style: Added some comments about PEP8 Olivier Delalleau <delallea@iro> parents: 1050 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 Documentation
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	221 -------------
1020 53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	222
53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	223 How do we write doc?
53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	224
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	225 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	226 ------------------------------------------
1020 53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	227
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	228 * 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	229
1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	230 * 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	231 compatible as possible with Python 3?
53f6eb80abf1 coding_style: More links and sections to discuss Olivier Delalleau <delallea@iro> parents: 1017 diff changeset	232
1025 1c96e7ad95c3 coding_style: Added discussion point about backward compatibility with Python 2.x versions Olivier Delalleau <delallea@iro> parents: 1022 diff changeset	233 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	234 --------------
1022 e21b3fdec4ef add comments. Frederic Bastien <nouiz@nouiz.org> parents: 1020 diff changeset	235
e21b3fdec4ef add comments. Frederic Bastien <nouiz@nouiz.org> parents: 1020 diff changeset	236 We also need a c-style coding style.
1033 f1e0a180574a coding_style: Added meeting date & time Olivier Delalleau <delallea@iro> parents: 1028 diff changeset	237
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	238 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	239 ------------------
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	240
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	241 * Coding guidelines
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	242 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	243 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	244
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	245 * Documentation
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	246 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	247 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	248 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	249 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	250 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	251
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	252 * 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	253 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	254 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	255 Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD)
1033 f1e0a180574a coding_style: Added meeting date & time Olivier Delalleau <delallea@iro> parents: 1028 diff changeset	256
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	257 * C coding style
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	258 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	259 Python.
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	260 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	261 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	262 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	263
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	264 * Program output
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	265 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	266 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	267 to use warning instead of logging. (DWF)
1033 f1e0a180574a coding_style: Added meeting date & time Olivier Delalleau <delallea@iro> parents: 1028 diff changeset	268
1062 64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	269 * Automatized code verification
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	270 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	271 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	272
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	273 * Tests
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	274 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	275 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	276 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	277 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	278 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	279 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	280 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	281
64720cdca3d3 coding_style: Notes from today's meeting and tasks for next week Olivier Delalleau <delallea@iro> parents: 1060 diff changeset	282 * 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	283 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	284 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	285 (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	286
1066 e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	287 Suggestion by PV
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	288 ----------------
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	289
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	290 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	291
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	292 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	293 -------------------------------------------------
1066 e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	294
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	295 * 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	296 lists:
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	297 - 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	298 the iteration)
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	299 - 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	300 - 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	301 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	302 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	303
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	304 Iterative version List version
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	305 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	306 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	307 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	308 itertools.imap map
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	309 itertools.ifilter filter
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	310 itertools.izip zip
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	311 xrange range
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	312
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	313 * 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	314 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	315 container types.
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	316
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	317 Yes No
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	318 --- --
e1aca94f28d8 coding_style: Added suggestion from PV, and a few coding guidelines Olivier Delalleau <delallea@iro> parents: 1062 diff changeset	319 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	320 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	321
1073 3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	322
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	323 * 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	324 easier to read.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	325 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	326 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	327 if not line.startswith('#')]
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	328 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	329 non_comments = map(str.strip,
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	330 filter(lambda line: not line.startswith('#'),
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	331 my_file.readlines()))
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	332
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	333 * 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	334 compatibility).
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	335 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	336 my_list.sort(key=abs)
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	337 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	338 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	339
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	340 * 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	341 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	342 n_samples_per_split = n_samples // n_splits
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	343 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	344 n_samples_per_split = n_samples / n_splits
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	345
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	346 * Only use ASCII characters in code files.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	347
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	348 * 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	349
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	350 * 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	351
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	352 * 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	353 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	354 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	355
1073 3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	356 * 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	357 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	358 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	359
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	360 * 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	361 to Python 3.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	362 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	363 def f(x, y_z):
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	364 y, z = y_z
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	365 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	366 def f(x, (y, z))
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	367
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	368 * Only use cPickle, not pickle.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	369
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	370 * Always raise exception with
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	371 raise MyException(args)
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	372 where MyException inherits from Exception.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	373
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	374 * 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	375 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	376
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	377 * 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	378 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	379 imported.
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	380
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	381 * 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	382 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	383 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	384
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	385 * 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	386 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	387 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	388
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	389 * 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	390 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	391 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	392
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	393 * 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	394 "except" with "finally" (which is not supported in Python 2.4).
1136 5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	395 You can make a try... except inside a try... finally if you need both.
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	396
1136 5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	397 * Do not use the `all` and `any` builtin functions (they are not supported
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	398 in Python 2.4).
1136 5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	399 You can use numpy.{all,any} instead of import theano.gof.python25 that
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	400 define all and any.
1138 9583e908c572 coding_style: Add a pylearn.compat module? Olivier Delalleau <delallea@iro> parents: 1136 diff changeset	401 OD: I think we should have something like pylearn.compat.{all,any}.
9583e908c572 coding_style: Add a pylearn.compat module? Olivier Delalleau <delallea@iro> parents: 1136 diff changeset	402 numpy.{all,any} are meant to be used on arrays only.
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	403 OD: As agreed during committee's meeting, we will use
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	404 theano.gof.python25
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	405
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	406 * Do not use the `hashlib` module (not supported in Python 2.4).
1136 5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	407 You can do as in theano.gof.cc:
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	408 ..code::
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	409 if sys.version_info[:2] >= (2,5):
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	410 import hashlib
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	411 def hash_from_code(msg):
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	412 return hashlib.md5(msg).hexdigest()
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	413 else:
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	414 import md5
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	415 def hash_from_code(msg):
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	416 return md5.new(msg).hexdigest()
1138 9583e908c572 coding_style: Add a pylearn.compat module? Olivier Delalleau <delallea@iro> parents: 1136 diff changeset	417 OD: Yep, we could probably come up with such a wrapper in a pylearn.compat
9583e908c572 coding_style: Add a pylearn.compat module? Olivier Delalleau <delallea@iro> parents: 1136 diff changeset	418 module.
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	419
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	420 * Do not use mutable arguments as default values. Instead, use a helper
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	421 function:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	422 Yes:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	423 def f(array=None):
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	424 array = pylearn.if_none(array, [])
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	425 No:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	426 def f(array=[]):
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	427 # Dangerous if `array` is modified down the road.
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	428
1075 d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	429 Mercurial commits
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	430 -----------------
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	431
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	432 * 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	433 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	434 * 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	435
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	436 During committee's meeting, Fred mentioned a bug with Assembla links for
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	437 multi-line commits.
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	438
1123 1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	439 Type checking
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	440 -------------
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	441
1123 1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	442 (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	443
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	444 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	445 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	446 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	447 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	448 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	449
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	450 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	451 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	452 fonction:
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	453
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	454 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	455
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	456 (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	457 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	458 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	459 ç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	460 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	461
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	462 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	463 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	464 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	465 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	466 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	467
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	468 OD: This was discussed in committee's meeting. We agreed to provide ways to do
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	469 this, but not to enforce its usage.
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	470
1130 aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	471 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	472 --------------------
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	473
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	474 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	475 (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	476 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	477 the code consistent).
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	478 OD: Approved during committee's meeting.
1130 aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	479
1132 f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	480 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	481 -------------------------------
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	482
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	483 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	484 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	485 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	486 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	487 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	488 (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	489 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	490 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	491 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	492 notifications.
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	493
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	494 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	495 `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	496 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	497 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	498 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	499 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	500 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	501
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	502 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	503 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	504 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	505 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	506 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	507 - 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	508 - 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	509
1140 7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	510 Meeting 2010/09/16
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	511 ------------------
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	512
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	513 Tasks to be performed by tomorrow:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	514 * OD:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	515 * Write down summary of Python coding style recommendations
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	516 * Start a file that showcases those guidelines
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	517 * DWF:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	518 * Look into recommendations on how to document a class, method, ...
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	519 * Write recommendations on when to use logging vs. warning
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	520 * Make public some configuration files / plugins for vim
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	521 * Come up with official common file header (license in particular)
1140 7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	522
1144 1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	523 Extended docstring standard (DWF)
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	524 ---------------------------------
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	525
1144 1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	526 In addition to the general guidelines of PEP 257, it is advised that we adopt
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	527 the NumPy docstring standard, or at least use it as a basis for formulating
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	528 our own.
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	529
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	530 Read the detailed docstring standard at
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	531
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	532 http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	533
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	534
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	535 logging module, the warning module, and when to use which
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	536 ---------------------------------------------------------
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	537
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	538 The logging module
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	539 ##################
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	540
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	541 A central logging facility for Python capable of logging messages of various
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	542 categories/urgency and choosing with some granularity which messages are
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	543 displayed/suppressed, as well as where they are displayed or written. This
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	544 includes an "INFO" level for innocuous status information, a "WARNING" level
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	545 for unexpected state that is still recoverable, "DEBUG" for detailed
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	546 information which is only really of interest when things are going wrong, etc.
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	547
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	548 In addition to the `library documentation`_, see this helpful tutorial,
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	549 `Python Logging 101`_.
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	550
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	551 .. _library documentation: http://docs.python.org/library/logging.html
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	552 .. _Python Logging 101: http://plumberjack.blogspot.com/2009/09/python-logging-101.html
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	553
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	554 The warning module
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	555 ##################
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	556
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	557 The warning module in the standard library and its main interface, the
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	558 warn() function, allows the programmer to issue warnings in situations where
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	559 they wish to alert the user to some condition, but the situation is not
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	560 urgent enough to throw an exception. By default, a warning issued at a given
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	561 line of the code will only be displayed the first time that line is executed.
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	562 By default, warnings are written to sys.stderr but the warning module
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	563 contains flexible facilities for altering the defaults, redirecting, etc.
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	564
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	565 Which? When?
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	566 ############
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	567
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	568 It's our feeling that the logging module's WARNING level be used to log
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	569 warnings more meant for internal, developer consumption, to log situations
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	570 where something unexpected happened that may be indicative of a problem but
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	571 it's several layers of abstraction below what a user of the library would
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	572 care about.
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	573
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	574 By contrast, the warning module should be used for warnings intended for user
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	575 consumption, e.g. alerting them that their version of pylearn is older than
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	576 this plugin requires, so things may not work as expected, or that a given
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	577 function/class/method is slated for deprecation in a coming release (early
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	578 in the library's lifetime, DeprecationWarnings will likely be the most common
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	579 case). The warning message issued through this facility should avoid
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	580 referring to pylearn internals.
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	581
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	582 Suggested per-file boilerplate
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	583 ------------------------------
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	584
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	585 """Module docstring as the first line, as usual."""
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	586
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	587 __authors__ = "Olivier Delalleau, Frederic Bastien, David Warde-Farley"
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	588 __copyright__ = "(c) 2010, Université de Montréal"
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	589 __license__ = "3-clause BSD License"
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	590 __contact__ = "Name Of Current Guardian of this file <email@address>"
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	591
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	592 We could also pull Mercurial revision info and put it in __version__, this
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	593 seems to be common.

Mercurial > pylearn

annotate doc/v2_planning/coding_style.txt @ 1144:1679742e7aa1