Ian Bicking wrote:
Ivan mentioned that there was someone willing to update all the OLPC
code once we have a style guide.
With that in mind I put together a draft of a style guide:
http://wiki.laptop.org/go/Python_Style_Guide
This is primarily a copy of PEP 8:
http://www.python.org/dev/peps/pep-0008/ -- I think we discussed most
of the variances the current code has from PEP 8 a couple months ago,
and I think everyone was okay with changing the code in those ways.
But of course, there were other things to attend to at the time;
having someone else volunteer to do the change makes this relevant again.
I've marked a number of things I'm unsure of with [note: ...].
Several of these are about code (and other file) layout issues, which
don't matter too much to an initial changeover of the code.
Internationalization style remains; I think someone besides myself
would be better at specifying the style for these.
We might want to consider setting up a pylint profile for this style.
pylint (http://www.logilab.org/projects/pylint) is notable among
Python source checkers for being anal about style and other small
details. Whoever is updating the code for the style might start out by
tweaking pylint until it can detect all the details we want to
update. It's also better to stick to the easy/mechanical updates to
start with, and avoid updates that might introduce bugs. Probably it
would make sense to annotate the style guide rules with "code already
should conform", "we will update current code" and "code will be
updated when possible".
Cool! Some comments:
> Use 4 spaces per indentation level. Do not use tabs.
Heh, I'm fine with this... we just need to convince Dan.
> Separate top-level function and class definitions with two blank lines.
Is this taken from PEP-8?
>__init__.py files should generally contain no substantive code.
Instead they should import from >other modules. Importing from other
modules is done so that a package can provide a front-facing >set of
objects and functions it exports, without exposing each of the internal
modules in the >package. Note however that this causes the submodules to
be eagerly imported; if this is likely to >cause unnecessary overhead
then the import in __init__.py should be reconsidered.
Can you give an example of this? I think it would be useful to have it
on the guide too. Is it part of PEP-8 in any way?
> Version bookkeeping
Doesn't sound particularly interesting to me. I'd probably just omit
that section.
> Module names
Might be worth motivating lowercase with other reasons than filesystem
compatibility (I think you gave better reasons on the list a while ago).
> [note: I don't think double underscore should ever be used; maybe
this should be removed]
I think it should, it's just confusing.
>For simple public data attributes, it is best to expose just the
attribute name, without complicated >accessor/mutator methods
I'm not sure I like this... It's quite unusual for non python coders. If
we want to keep it we should probably elaborate more on it in the guide.
*> Comparisons to singletons like None should always be done with 'is'
or 'is not', never the equality operators.*
Is this just style or does it have other consequences?
*> For sequences, (strings, lists, tuples), use the fact that empty
sequences are false.
Nice one!
*> Is _() always defined?
Nope, I think you need to import it from gettext.
Anyway, great stuff. Let's try to finalize and start using it.
Marco
_______________________________________________
Sugar mailing list
[email protected]
http://mailman.laptop.org/mailman/listinfo/sugar
