pylearn: doc/v2_planning/coding

annotate doc/v2_planning/coding_style.txt @ 1150:d7192e52653e

coding_style: Moved some elements to official API

author	Olivier Delalleau <delallea@iro>
date	Thu, 16 Sep 2010 17:00:58 -0400
parents	f6011a2aff0b
children	0904dd74894d

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
1073 3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	295
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	296 * 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	297 compatibility).
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	298 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	299 my_list.sort(key=abs)
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	300 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	301 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	302
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	303 * 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	304 Yes:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	305 n_samples_per_split = n_samples // n_splits
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	306 No:
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	307 n_samples_per_split = n_samples / n_splits
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	308
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	309 * Only use ASCII characters in code files.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	310
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	311 * 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	312
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	313 * 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	314
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	315 * 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	316 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	317 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	318
1073 3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	319 * 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	320 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	321 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	322
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	323 * 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	324 to Python 3.
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 def f(x, y_z):
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	327 y, z = y_z
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 def f(x, (y, z))
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	330
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	331 * Only use cPickle, not pickle.
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 * Always raise exception with
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	334 raise MyException(args)
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	335 where MyException inherits from Exception.
3e7978201ffc coding_style: Some more python coding guidelines Olivier Delalleau <delallea@iro> parents: 1070 diff changeset	336
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	337 * 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	338 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	339
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	340 * 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	341 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	342 imported.
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	343
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	344 * 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	345 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	346 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	347
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	348 * 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	349 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	350 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	351
1133 9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	352 * 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	353 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	354 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	355
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	356 * 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	357 "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	358 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	359
1136 5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	360 * 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	361 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	362 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	363 define all and any.
1138 9583e908c572 coding_style: Add a pylearn.compat module? Olivier Delalleau <delallea@iro> parents: 1136 diff changeset	364 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	365 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	366 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	367 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	368
9baa47482ccc coding_style: Added a few more coding guidelines for compatibility with various Python versions Olivier Delalleau <delallea@iro> parents: 1132 diff changeset	369 * 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	370 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	371 ..code::
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	372 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	373 import hashlib
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	374 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	375 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	376 else:
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	377 import md5
5f0c8ff2b3b6 tell how do to some stuff to be compatible with python2.4 Frederic Bastien <nouiz@nouiz.org> parents: 1134 diff changeset	378 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	379 return md5.new(msg).hexdigest()
1138 9583e908c572 coding_style: Add a pylearn.compat module? Olivier Delalleau <delallea@iro> parents: 1136 diff changeset	380 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	381 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	382
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	383 * 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	384 function:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	385 Yes:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	386 def f(array=None):
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	387 array = pylearn.if_none(array, [])
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	388 No:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	389 def f(array=[]):
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	390 # 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	391
1075 d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	392 Mercurial commits
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	393 -----------------
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	394
d422f726c156 coding_style: Discussion and one more point to think about Olivier Delalleau <delallea@iro> parents: 1074 diff changeset	395 * 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	396 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	397 * 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	398
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	399 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	400 multi-line commits.
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	401
1123 1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	402 Type checking
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	403 -------------
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	404
1123 1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	405 (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	406
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	407 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	408 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	409 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	410 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	411 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	412
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	413 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	414 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	415 fonction:
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	416
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	417 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	418
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	419 (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	420 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	421 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	422 ç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	423 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	424
1a1c0c3adcca coding_style: Added suggestion made by email by Francois about type checking Olivier Delalleau <delallea@iro> parents: 1113 diff changeset	425 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	426 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	427 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	428 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	429 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	430
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	431 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	432 this, but not to enforce its usage.
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	433
1130 aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	434 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	435 --------------------
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	436
aae62c4b2e9f coding_style: Added a new point to discuss, about which inf/nan to use Olivier Delalleau <delallea@iro> parents: 1128 diff changeset	437 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	438 (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	439 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	440 the code consistent).
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	441 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	442
1132 f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	443 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	444 -------------------------------
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	445
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	446 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	447 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	448 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	449 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	450 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	451 (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	452 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	453 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	454 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	455 notifications.
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	456
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	457 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	458 `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	459 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	460 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	461 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	462 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	463 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	464
f0a1b88367b0 coding_style: Looked into feasibility of forcing developers to test their code Olivier Delalleau <delallea@iro> parents: 1130 diff changeset	465 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	466 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	467 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	468 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	469 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	470 - 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	471 - 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	472
1140 7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	473 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	474 ------------------
7d2e65249bf9 coding_style: Closed some open questions for which a decision was reached during meeting Olivier Delalleau <delallea@iro> parents: 1138 diff changeset	475
1141 6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	476 Tasks to be performed by tomorrow:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	477 * OD:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	478 * 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	479 * Start a file that showcases those guidelines
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	480 * DWF:
6c79394b6b20 coding_style: Decisions made during today's meeting Olivier Delalleau <delallea@iro> parents: 1140 diff changeset	481 * 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	482 * 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	483 * 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	484 * 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	485
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	486 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	487 ------------------------------
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	488
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	489 """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	490
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	491 __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	492 __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	493 __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	494 __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	495
1679742e7aa1 Writing related to the tasks assigned to me at today's meeting. David Warde-Farley <wardefar@iro.umontreal.ca> parents: 1141 diff changeset	496 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	497 seems to be common.

Mercurial > pylearn

annotate doc/v2_planning/coding_style.txt @ 1150:d7192e52653e