Google's Python style guide

http://google-styleguide.googlecode.com/svn/trunk/pyguide.html

by cr4zy • 14 years ago

130 86 14 years ago

google-styleguide.googlecode.com

droctopu5• 14 years ago

Wait, I thought Python WAS a style guide.

iloveponies• 14 years ago

Interesting they make no reference to PEP 8.

cr4zy• 14 years ago

Yeah, especially since this old one does. http://code.google.com/p/soc/wiki/PythonStyleGuide#Naming

slurgfest2• 14 years ago

"Interesting" isn't the word I'd use - PEP 8 is pretty clearly ratified by the Python community (more than any other style) and yet Google Knows Best

thristian• 14 years ago

The Google style guide seems to match up with PEP 8 pretty closely, from my brief review of it. Better yet, it actually includes explicit guidance on things like 'how to name local variables and class properties' which PEP 8 is mysteriously silent on.

yuvadam• 14 years ago

Weird. The recommendation for a shebang line is to use #!/usr/bin/python

That will definitely break stuff. Why not #!/usr/bin/env python?

nikcub4• 14 years ago

env is nothing more than running it in a new shell, so slightly slower for each exec (since it starts a shell and then searches through PATH), may pick the wrong interpreter (because PATH is dependent on the user and a lot of other things outside of your control) and since this is all running on Google infrastructure they know what /usr/bin/python.

their goal isn't to write portable code, it is to write fast code that runs on google servers

etanol• 14 years ago

Sorry, but I fail to see where the "env" command spawns a shell:

http://git.savannah.gnu.org/cgit/coreutils.git/tree/src/env....

Could you please explain what am I missing?

AncientPC5• 14 years ago

I wrote a few small scripts to test this out. Each contained a simple print statement, then looped it 5000 times and timed it.

There is ~2.1% overhead when using env.

This doesn't matter in most cases, but in a Google-sized company with standardized environments it's worth it.

nodata4• 14 years ago

Maybe because it's a hack because to get around the following not working?

#!python

emmelaich3• 14 years ago

Yes; #!python should be made to work.

Not to use the user's PATH, but some system ordained python (via some kernel work).

env is a hack.

rbanffy8• 14 years ago

Bad idea. Which python (or program named "python") will run your script?

qznc• 14 years ago

I like the idea to include a name with TODOs, like

  # TODO(qznc) check Unicode handling

This never occured to me, but it provides a good pointer whom to ask for details. On the other hand git-blame should be able to provide the same info.

anatoly• 14 years ago

This is also convenient for when you want to pay back technical debt and fix some of the old TODOs: you can search the codebase for those with your name on them.

AncientPC5• 14 years ago

If you're working with a Git repository, there's always `git blame` (http://schacon.github.com/git/git-blame.html).

minimax• 14 years ago

Seems to be a Google-ism. I haven't worked there, but all the ex-Googlers I've worked with do this. It also makes it easy to grep for all your TODOs in a tree, something you can't do with cvs/svn/git annotate.

Aissen• 14 years ago

> something you can't do with cvs/svn/git annotate.

Challenge accepted:

  for i in $(git grep -l TODO); do git blame -f $i |grep TODO |grep "$NAME"; done

Granted, it can be long on a big codebase, but does the trick.

viraptor2• 14 years ago

I hate those. Unless you're familiar with the whole team you don't know who qznc is. Git/hg/svn blame will tell you that more precisely. Inserting your name in the comment is only slightly less annoying than people insisting to put "author"comments on top of the file (or even a function)

tonfa3• 14 years ago

And you don't have an easy to find out who he is? Or mail him based on his username?

sp332• 14 years ago

I guess you could use "git blame" to find the name and email of the person who added that line?

pavel_lishin• 14 years ago

I prefer something like

    #TODO #4001 needs more bananas

Where 4001 references something in our bug tracker (task, feature, issue, bug, etc.)

lclarkmichalek• 14 years ago

The last point is definitely the most important, and applies to any language

waleedka• 14 years ago

Interestingly, the Python code I've seen from Google uses 2-space indents rather than 4 as the style guide recommends. And that includes code written by Guido himself (AppStats and NDB, tools used in App Engine). I prefer 2 spaces as well, and I was hoping that the official style guide would match what's being used most commonly.

rachelbythebay• 14 years ago

One easy way to break your brain is to work at Google... on an open source Python project. Two, four... two, four...

It could be far worse.

AncientPC5• 14 years ago

I don't mean to start yet another tabs vs spaces debate, but I've always felt spaces dictate how others see the code while tabs allowed others to see code however they like (2/4/8 spaces).

One exception is some projects are strict about lining up code properly in multi-line statements, and spaces are more consistent in that respect.

I prefer tabs, but most Python code I've seen has been 4 space indents.

toyg2• 14 years ago

I used to prefer tabs (less bytes, better abstraction etc), but I've long given up on it. Most tools are not smart enough to switch mode when required, and reformatting entire files every time you want to make a small change on somebody else's code is a real pain (and dangerous).

Community consensus is 4-spaces and that's it.

kami88452• 14 years ago

They used to recommend 2 spaces (you can probably check the page with archive.org) but have switched to 4.

Locke16892• 14 years ago

This is very weird, because the internal style guidelines say 2 spaces, not 4 spaces. This bugs me quite a lot.

plq• 14 years ago

> Never use catch-all except: statements, or catch Exception or StandardError, unless you are re-raising the exception or in the outermost block in your thread (and printing an error message). Python is very tolerant in this regard and except: will really catch everything including Python syntax errors. It is easy to hide real bugs using except:.

What kind of SyntaxErrors are cought by the except: handler? Not all, I presume:

  try:
    a b
  except:
    pass

This fails with SyntaxError on Python 2.7.2 on my machine.

mxey• 14 years ago

That code is never executed because it fails to parse. I think you can catch SyntaxError if you import a file with broken syntax.

grifaton• 14 years ago

This would catch a SyntaxError raised by eval().

For example,

    try:
        eval(".")
    except:
        pass

shawnps• 14 years ago

Regarding this one:

http://google-styleguide.googlecode.com/svn/trunk/pyguide.ht...

I commented about this on another post. There's a nice explanation here as to why using mutable objects as default values in function/method definitions is bad:

http://effbot.org/zone/default-values.htm

In short, it can be bad to set default arguments to mutable objects because the function keeps using the same object in each call.

toyg2• 14 years ago

That's a classic Python gotcha, mentioned in all books and tutorials nowadays.

maybe_someday• 14 years ago

I wonder why pyChecker and not pyLint or pep8. Anyone got an insight?

tonfa3• 14 years ago

Pylint is used internally: http://comments.gmane.org/gmane.comp.python.logilab/1075

danso• 14 years ago

For an offhand comparison: Google's unofficial Ruby style guide:

http://www.caliban.org/ruby/rubyguide.shtml

willvarfar• 14 years ago

Fun fact: Google recommend against using map/reduce :)

http://google-styleguide.googlecode.com/svn/trunk/pyguide.ht...

Oh, not different map/reduce? ;)

AncientPC5• 14 years ago

One of the nice things about using map() is multiprocessing.Pool.map() can be a drop-in replacement.

OTOH, map() does otherwise have a little overhead compared to list comprehension.

jbarham• 14 years ago

Much as I like the general consistency of Python code with or without formal style guides, I prefer Go's "style guide" even more, which is to just run "go fmt": http://golang.org/cmd/go/#Run_gofmt_on_package_sources.

slurgfest2• 14 years ago

You could just run pep8, you know.

acdha• 14 years ago

"gofmt -w" actually rewrites the files. I'd love a Python formatter which applies the robotic parts of PEP-8 automatically so you could focus on the parts which require more thought.

rbanffy8• 14 years ago

I'll continue surrounding "="s in keyword arguments and default parameter values regardless of what PEP-8 says.

jdevera4• 14 years ago

Why oh why the 80 character limit? It's the 21st century, screens are huge! I'm not saying let's put the limit in 300, but 100 or 120 is good enough to fit side by side diffs in one screen.

raverbashing2• 14 years ago

There are 2 issues there

1 - yes, screens are huge, but it doesn't mean people can/will use small fonts or will scroll the screen

With today's big/wide screens it's more useful to have code side by side.

2 - Abuse. The 80 character limit is a pretty good indicator that you should be doing something else instead of having your code go over 80 characters.

Long lines are confusing, and you most likely can split the logic in several lines, facilitating maintenance.

jdevera4• 14 years ago

I see both points but regarding (2), there are common cases where you are not necessarily doing anything wrong but the 80 character limit will make your code less readable, especially when using four spaces or more for indentation. For example you might end up in the fourth level of indentation wanting to write a list comprehension that would be perfectly readable in one line but have to break it down because of this rather short hard limit.

I think having a soft and a hard limit makes more sense, if anything, I would make 80 characters the soft limit and perhaps 100 a hard limit, although I'd prefer them to be 100 and 120.

khill• 14 years ago

I find that limiting line length to 80 characters causes some programmers to use overly terse variable names. This hurts code readability and can hide defects.

arethuza• 14 years ago

I've recently started developing in Python (after developing in many other languages) and I thought I would find the 80-character limit from PEP 8 a problem.

However, I've actually found it to be a good thing - I'm sure it aids readability.

pbreit• 14 years ago

Because it's easier for a human to read. It has nothing to do with prevailing screen sizes.

jdevera4• 14 years ago

My point is that having 80 characters as a hard limit sometimes imposes some linebreaks that negatively affect readability. My mention of the screen sizes comes from the fact that the 80 character limit originally was set to fit the code in a 80x24 character terminal without non-explicit line wraps.

Locke16892• 14 years ago

Depending slightly on your font size, 3 80-column lines fit side-by-side almost perfectly on a 30" monitor.

nikcub4• 14 years ago

I don't like Google's import style, and I have noticed it in a lot of their code. They nicely namespace all of their packages and modules only to dump methods and classes into a single namespace when being imported and used.

for eg.

    from sound.effects import echo
    echo.EchoFilter(input, output)

What happens is that you then end up importing all of these methods and very quickly you start getting name conflicts. Lets say you want to support a third-party echo function:

    from sound.effects import echo
    from vendor.soundutil.effects import echo as soundutil_echo

You see this all the time in SDK and web API packages. Dozens of modules called 'auth' (which auth? twitter? facebook?) or 'oauth' or 'request'.

Lets say you have a user page that integrates with social networks, would you rather:

    from facebook.api.auth import auth
    from twitter.api.auth import twitter_auth

etc. etc. or

    import facebook.api
    import twitter.api
    ..
    facebook.api.auth()
    twitter.api.auth()

You end up either doing 'import as' hacks and a lot of renaming. Code is a lot clearer to read when you see full method names such as facebook.api.auth rather than just 'auth' and 'echo' everywhere. You also don't lose documentation paths.

My general rule of thumb is to use 'from' infrequently, never do import *, to retain the part of the path that still keeps namespacing sane and clear to the developer and as the doc says to never do relative imports.

It means you can scan any part of the code and understand what is going on without going back up to the top of the file. Also makes search/replace easier (rather than s/echo/echo_new s/sound.effects.echo/mynewpackage.echo)

The other one I didn't see mentioned is nesting levels and method lengths. Python isn't well suited to deep-nested and long methods. Especially if your coding style is to comment out blocks of code during development as you test things, you always end up commenting out parts and then having to re-indent the rest of it.

The same usually applies if you have long 'and' 'or' clauses in ifs that span multiple lines and make it harder to understand the code. I usually wrap those tests into separate methods (if you are using them once, you will probably use them again)

but for nesting, I try to stick to 2 levels max. If you go beyond that it is usually a hint that you can refactor the codepath and perhaps even separate out into another method.

I just happen to be doing this a few hours ago while writing an option and argument parser for a command line utility that has sub-commands. a quick re-factor made the code and all the different options and which options apply to which sub-commands a lot easier to understand

Edit: just further on breaking up code and bounds checking into methods, it makes life easier for other developers and for your future self. there is nothing more exhausting than trying to debug a module and finding a 3-page long method called 'run', which you end up having to break down yourself anyway. separate all the bounds checking into one or two line methods, break everything else up, document it, write some tests for it and then forget about it - that is done and it works. get on with important things.

checking nesting levels and method length is almost something I would want to put in a linter

kami88452• 14 years ago

it can get confusing when you import a lot of things, but for quick prototyping I prefer to just do `from package.this import that` and then be able to `that.execute(element)` instead of having to type `package.this.that.execute(element)` every single time. (which already takes up 34 characters of the 80 char limit)

oddthink• 14 years ago

I find it's easier to have short names, defined at the beginning, rather than clogging up my code with full.path.to.a.module. I imagine preferences vary.

What I don't understand is why they prefer:

    from thepackage.subpackage import amodule

over

    import thepackage.subpackage.amodule as amodule

I always found the second to be more clear, since it doesn't mix the idea of package-resolution with the idea of picking-things-out-of-a-module. On the down side, I end up typing "amodule" twice.

scorpion0322• 14 years ago

"List Comprehensions: Ok to use for simple cases (only)": http://google-styleguide.googlecode.com/svn/trunk/pyguide.ht...

Really, Google? I find the following far more convenient to read:

    result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]

Than the alternative:

    result = []
    for x in range(10):
        for y in range(5):
            if x * y > 10:
                result.append((x, y))

ironchef2• 14 years ago

I found the alternative easier to read. I read it once. I had to scan yours twice. I'd say yours is borderline simple case.

Also, i think part of the difference can be found when you're dealing with large amounts of code in maintenance. I'd much rather read something dead simple (if somewhat verbose) than something that makes me think at all (another example here would be (in the ruby world) use of !unless).

Like anything that has to do with taste, to each their own (i prefer a vinegary bbq while you might like a smokier bbq)

RyanMcGreal• 14 years ago

I didn't like list comprehensions when I first encountered them, but after getting accustomed to them, I now strongly prefer to write and read a comprehension over a for-in loop.

rbanffy8• 14 years ago

It would be more readable to write it as:

    result = [(x, y) for x in range(10) 
                     for y in range(5) 
                     if x * y > 10]

Anyway, I'd call it a simple case.

Also, it has nice semantics - the second example has a clear execution order. This one doesn't - it can all happen at once, from the program's perspective and unless you make assumptions about order in which the items are calculated (as opposed to returned), they don't even need to be all ready before you start iterating on them. If you assume it can happen at once, the list comprehensions can be neatly mapped to parallel computations.

So, it shouldn't be that hard to optimize something like:

    data = [sin(x) for x in arange(0, pi, pi/20)]

to run on a GPU.

edit: small clarifications

jerf2• 14 years ago

"the second example has a clear execution order. This one doesn't - it can all happen at once, from the program's perspective"

I'm not sure what you're getting at here. With Python list comprehension semantics, those are both the same, including execution order. I don't see any ambiguity or need for "assumptions about the order of results". Am I missing something?

Optimization of Python list comprehensions to run on a GPU would take some serious mojo to ensure independence of each clause. Not an impossible amount, but certainly not trivial, especially as you move beyond calling 'sin'.

Wilduck• 14 years ago

Your first example is easier for me to read, but only in the case that I don't care about the order of (x, y) points.

If I care that (3, 6) comes before (4, 4), I find it much easier to ascertain that from the form that uses indentation for nesting loops.

kbd• 14 years ago

List comprehensions iterate in the same order as the for loops. If it helps, stick a mental newline in there :P

    [(x, y) for x in range(10)
    for y in range(5)...]

gaius• 14 years ago

Not only that, try running dis() on each of those and seeing what bytecode gets executed...

scorpion0322• 14 years ago

Right. List comprehensions even perform better.

silon4• 14 years ago

Personally, in my own code I also like to put pass at the end of all blocks. It's more consistent, and it also makes auto indent in the editors work properly. Anyone else?

Google's Python style guide

Related Stories