Update C++ style guide to 3.154:
- Add call_traits to the set of allowed boost libraries.
- Add an exception to the rule against default arguments to cover the useful
case of simulating variadic functions.
- Discourage the usage of ## in macros.
- Clarify example: it's acceptable to declare two parameters on one line even
if they don't all fit on that one line.
- Fix a typo ("make use symmetric spacing").
- Change bitwise AND to logical AND in a condition.
Update styleguide.xsl to 1.27:
- Change a bunch of SPANs into DIVs.
Update Python style guide to 2.15:
- Apply styleguide.xsl 1.27, changing a bunch of SPANs into DIVs.
diff --git a/pyguide.html b/pyguide.html
index 2bf4363..46769a3 100644
--- a/pyguide.html
+++ b/pyguide.html
@@ -94,7 +94,7 @@
<H1>Google Python Style Guide</H1>
<p align="right">
- Revision 2.14
+ Revision 2.15
</p>
<address>
@@ -133,16 +133,19 @@
</TABLE>
</DIV>
<H2>Overview</H2>
- <SPAN class=""><H2 name="Important_Note" id="Important_Note">Important Note</H2>
- <SPAN class=""><H3><A name="Displaying_Hidden_Details_in_this_Guide" id="Displaying_Hidden_Details_in_this_Guide">Displaying Hidden Details in this Guide</A></H3>
+ <DIV class="">
+<H2 name="Important_Note" id="Important_Note">Important Note</H2>
+ <DIV class="">
+<H3><A name="Displaying_Hidden_Details_in_this_Guide" id="Displaying_Hidden_Details_in_this_Guide">Displaying Hidden Details in this Guide</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Displaying_Hidden_Details_in_this_Guide__body','Displaying_Hidden_Details_in_this_Guide__button')" name="Displaying_Hidden_Details_in_this_Guide__button" id="Displaying_Hidden_Details_in_this_Guide__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
This style guide contains many details that are initially
hidden from view. They are marked by the triangle icon, which you
see here on your left. Click it now.
You should see "Hooray" appear below.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Displaying_Hidden_Details_in_this_Guide__body" id="Displaying_Hidden_Details_in_this_Guide__body" style="display: none"><SPAN class="link_button"><A href="?showone=Displaying_Hidden_Details_in_this_Guide#Displaying_Hidden_Details_in_this_Guide">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Displaying_Hidden_Details_in_this_Guide__body" id="Displaying_Hidden_Details_in_this_Guide__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Displaying_Hidden_Details_in_this_Guide#Displaying_Hidden_Details_in_this_Guide">
link
</A></SPAN>
<p>
@@ -150,10 +153,11 @@
details. Alternatively, there's a "toggle all" at the
top of this document.
</p>
- </SPAN></SPAN>
- </SPAN>
- </SPAN>
- <SPAN class=""><H2 name="Background" id="Background">Background</H2>
+ </DIV></DIV>
+ </DIV>
+ </DIV>
+ <DIV class="">
+<H2 name="Background" id="Background">Background</H2>
<p>
Python is the main scripting language used at Google. This
style guide is a list of <em>do</em>s and <em>don't</em>s for Python
@@ -162,16 +166,19 @@
- </SPAN>
+ </DIV>
- <SPAN class=""><H2 name="Python_Language_Rules" id="Python_Language_Rules">Python Language Rules</H2>
+ <DIV class="">
+<H2 name="Python_Language_Rules" id="Python_Language_Rules">Python Language Rules</H2>
- <SPAN class=""><H3><A name="pychecker" id="pychecker">pychecker</A></H3>
+ <DIV class="">
+<H3><A name="pychecker" id="pychecker">pychecker</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('pychecker__body','pychecker__button')" name="pychecker__button" id="pychecker__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Run <code>pychecker</code> over your code.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="pychecker__body" id="pychecker__body" style="display: none"><SPAN class="link_button"><A href="?showone=pychecker#pychecker">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="pychecker__body" id="pychecker__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=pychecker#pychecker">
link
</A></SPAN>
<P class="">
@@ -207,8 +214,8 @@
<code>__pychecker__</code> to suppress appropriate warnings.
For example:
</p>
- <SPAN class=""><PRE>
-<span class="external"></span>__pychecker__ = 'no-callinit no-classattr'</PRE></SPAN>
+ <DIV class=""><PRE>
+<span class="external"></span>__pychecker__ = 'no-callinit no-classattr'</PRE></DIV>
<p>
Suppressing in this way has the advantage that we can easily search
for suppressions and revisit them.
@@ -224,25 +231,27 @@
infeasible, you can mention them at the beginning of the function.
For example:
</p>
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>def foo(a, unused_b, unused_c, d=None, e=None):
<span class="external"> </span>(d, e) = (d, e) # Silence pychecker
<span class="external"> </span>return a
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
<p>
Ideally, pychecker would be extended to ensure that such `unused
declarations' were true.
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Imports" id="Imports">Imports</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Imports" id="Imports">Imports</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports__body','Imports__button')" name="Imports__button" id="Imports__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use <code>import</code>s for packages and modules only.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Imports__body" id="Imports__body" style="display: none"><SPAN class="link_button"><A href="?showone=Imports#Imports">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Imports__body" id="Imports__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Imports#Imports">
link
</A></SPAN>
<P class="">
@@ -268,12 +277,12 @@
package prefix. For example the module
<code>sound.effects.echo</code> may be imported as follows:
</P>
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>from sound.effects import echo
<span class="external"></span>...
<span class="external"></span>echo.echofilter(input, output, delay=0.7, atten=4)
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
<p>
Even if the module is in the same package, do not directly import
the module without the full package name. This might cause the
@@ -281,15 +290,17 @@
"main" module that is used to start an application lives inside a
package (and uses modules from that same package).
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Packages" id="Packages">Packages</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Packages" id="Packages">Packages</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Packages__body','Packages__button')" name="Packages__button" id="Packages__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Import and refer to each module using the full pathname location of
that module.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Packages__body" id="Packages__body" style="display: none"><SPAN class="link_button"><A href="?showone=Packages#Packages">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Packages__body" id="Packages__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Packages#Packages">
link
</A></SPAN>
<P class="">
@@ -311,21 +322,23 @@
</p>
- <SPAN class=""><PRE># Reference in code with complete name.
+ <DIV class=""><PRE># Reference in code with complete name.
import sound.effects.echo
# Reference in code with just module name.
from sound.effects import echo
-</PRE></SPAN>
+</PRE></DIV>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Exceptions" id="Exceptions">Exceptions</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Exceptions" id="Exceptions">Exceptions</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Exceptions__body','Exceptions__button')" name="Exceptions__button" id="Exceptions__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Exceptions are allowed but must be used carefully.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Exceptions__body" id="Exceptions__body" style="display: none"><SPAN class="link_button"><A href="?showone=Exceptions#Exceptions">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Exceptions__body" id="Exceptions__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Exceptions#Exceptions">
link
</A></SPAN>
<P class="">
@@ -362,9 +375,9 @@
base exception class, which should inherit from the built-in
Exception class. The base exception for a module should be called
<code>Error</code>.
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>class Error(Exception):
- <span class="external"> </span>pass</PRE></SPAN>
+ <span class="external"> </span>pass</PRE></DIV>
</li>
<li>Never use catch-all <code>except:</code> statements, or
catch <code>Exception</code> or <code>StandardError</code>,
@@ -385,14 +398,16 @@
This is often useful for cleanup, i.e., closing a file.</li>
</ul>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Global_variables" id="Global_variables">Global variables</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Global_variables" id="Global_variables">Global variables</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Global_variables__body','Global_variables__button')" name="Global_variables__button" id="Global_variables__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Avoid global variables.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Global_variables__body" id="Global_variables__body" style="display: none"><SPAN class="link_button"><A href="?showone=Global_variables#Global_variables">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Global_variables__body" id="Global_variables__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Global_variables#Global_variables">
link
</A></SPAN>
<P class="">
@@ -425,14 +440,16 @@
see <a HREF="#Naming">Naming</a> below.</li>
</ul>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Nested/Local/Inner_Classes_and_Functions" id="Nested/Local/Inner_Classes_and_Functions">Nested/Local/Inner Classes and Functions</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Nested/Local/Inner_Classes_and_Functions" id="Nested/Local/Inner_Classes_and_Functions">Nested/Local/Inner Classes and Functions</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Nested/Local/Inner_Classes_and_Functions__body','Nested/Local/Inner_Classes_and_Functions__button')" name="Nested/Local/Inner_Classes_and_Functions__button" id="Nested/Local/Inner_Classes_and_Functions__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Nested/local/inner classes and functions are fine.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Nested/Local/Inner_Classes_and_Functions__body" id="Nested/Local/Inner_Classes_and_Functions__body" style="display: none"><SPAN class="link_button"><A href="?showone=Nested/Local/Inner_Classes_and_Functions#Nested/Local/Inner_Classes_and_Functions">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Nested/Local/Inner_Classes_and_Functions__body" id="Nested/Local/Inner_Classes_and_Functions__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Nested/Local/Inner_Classes_and_Functions#Nested/Local/Inner_Classes_and_Functions">
link
</A></SPAN>
<P class="">
@@ -454,14 +471,16 @@
<SPAN class="stylepoint_section">Decision: </SPAN>
They are fine.
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="List_Comprehensions" id="List_Comprehensions">List Comprehensions</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="List_Comprehensions" id="List_Comprehensions">List Comprehensions</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('List_Comprehensions__body','List_Comprehensions__button')" name="List_Comprehensions__button" id="List_Comprehensions__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Okay to use for simple cases.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="List_Comprehensions__body" id="List_Comprehensions__body" style="display: none"><SPAN class="link_button"><A href="?showone=List_Comprehensions#List_Comprehensions">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="List_Comprehensions__body" id="List_Comprehensions__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=List_Comprehensions#List_Comprehensions">
link
</A></SPAN>
<P class="">
@@ -491,7 +510,7 @@
permitted. Use loops instead when things get more complicated.
</P>
-<SPAN class=""><PRE class="badcode">No<span class="external"></span>:
+<DIV class=""><PRE class="badcode">No<span class="external"></span>:
<span class="external"></span>result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
<span class="external"></span>return ((x, y, z)
@@ -499,8 +518,8 @@
<span class="external"></span> for y in xrange(5)
<span class="external"></span> if x != y
<span class="external"></span> for z in xrange(5)
- <span class="external"></span> if y != z)</PRE></SPAN>
-<SPAN class=""><PRE>Ye<span class="external"></span>s:
+ <span class="external"></span> if y != z)</PRE></DIV>
+<DIV class=""><PRE>Ye<span class="external"></span>s:
<span class="external"></span>result = []
<span class="external"></span>for x in range(10):
<span class="external"> </span>for y in range(5):
@@ -521,16 +540,18 @@
<span class="external"></span>squares = [x * x for x in range(10)]
<span class="external"></span>eat(jelly_bean for jelly_bean in jelly_beans
- <span class="external"></span> if jelly_bean.color == 'black')</PRE></SPAN>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Default_Iterators_and_Operators" id="Default_Iterators_and_Operators">Default Iterators and Operators</A></H3>
+ <span class="external"></span> if jelly_bean.color == 'black')</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Default_Iterators_and_Operators" id="Default_Iterators_and_Operators">Default Iterators and Operators</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Iterators_and_Operators__body','Default_Iterators_and_Operators__button')" name="Default_Iterators_and_Operators__button" id="Default_Iterators_and_Operators__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use default iterators and operators for types that support them,
like lists, dictionaries, and files.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Default_Iterators_and_Operators__body" id="Default_Iterators_and_Operators__body" style="display: none"><SPAN class="link_button"><A href="?showone=Default_Iterators_and_Operators#Default_Iterators_and_Operators">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Default_Iterators_and_Operators__body" id="Default_Iterators_and_Operators__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Default_Iterators_and_Operators#Default_Iterators_and_Operators">
link
</A></SPAN>
<P class="">
@@ -557,23 +578,25 @@
methods to methods that return lists, except that you should not
mutate a container while iterating over it.
-<SPAN class=""><PRE>Yes: <span class="external"></span>for key in adict: ...
+<DIV class=""><PRE>Yes: <span class="external"></span>for key in adict: ...
<span class="external"></span>if key not in adict: ...
<span class="external"></span>if obj in alist: ...
<span class="external"></span>for line in afile: ...
- <span class="external"></span>for k, v in dict.iteritems(): ...</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>for key in adict.keys(): ...
+ <span class="external"></span>for k, v in dict.iteritems(): ...</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>for key in adict.keys(): ...
<span class="external"></span>if not adict.has_key(key): ...
- <span class="external"></span>for line in afile.readlines(): ...</PRE></SPAN>
+ <span class="external"></span>for line in afile.readlines(): ...</PRE></DIV>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Generators" id="Generators">Generators</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Generators" id="Generators">Generators</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Generators__body','Generators__button')" name="Generators__button" id="Generators__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use generators as needed.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Generators__body" id="Generators__body" style="display: none"><SPAN class="link_button"><A href="?showone=Generators#Generators">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Generators__body" id="Generators__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Generators#Generators">
link
</A></SPAN>
<P class="">
@@ -598,14 +621,16 @@
Fine. Use "Yields:" rather than "Returns:" in the
doc string for generator functions.
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Lambda_Functions" id="Lambda_Functions">Lambda Functions</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Lambda_Functions" id="Lambda_Functions">Lambda Functions</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lambda_Functions__body','Lambda_Functions__button')" name="Lambda_Functions__button" id="Lambda_Functions__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Okay for one-liners.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Lambda_Functions__body" id="Lambda_Functions__body" style="display: none"><SPAN class="link_button"><A href="?showone=Lambda_Functions#Lambda_Functions">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Lambda_Functions__body" id="Lambda_Functions__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Lambda_Functions#Lambda_Functions">
link
</A></SPAN>
<P class="">
@@ -637,14 +662,16 @@
x, y: x * y</code>.
</p>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Default_Argument_Values" id="Default_Argument_Values">Default Argument Values</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Default_Argument_Values" id="Default_Argument_Values">Default Argument Values</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Argument_Values__body','Default_Argument_Values__button')" name="Default_Argument_Values__button" id="Default_Argument_Values__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Okay in most cases.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Default_Argument_Values__body" id="Default_Argument_Values__body" style="display: none"><SPAN class="link_button"><A href="?showone=Default_Argument_Values#Default_Argument_Values">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Default_Argument_Values__body" id="Default_Argument_Values__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Default_Argument_Values#Default_Argument_Values">
link
</A></SPAN>
<P class="">
@@ -680,32 +707,34 @@
Do not use mutable objects as default values in the function or method
definition.
</p>
-<SPAN class=""><PRE>Yes: <span class="external"></span>def foo(a, b=None):
+<DIV class=""><PRE>Yes: <span class="external"></span>def foo(a, b=None):
<span class="external"> </span>if b is None:
- <span class="external"> </span>b = []</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>def foo(a, b=[]):
- <span class="external"> </span>...</PRE></SPAN>
+ <span class="external"> </span>b = []</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>def foo(a, b=[]):
+ <span class="external"> </span>...</PRE></DIV>
<p>
Calling code must use named values for arguments with a default value.
This helps document the code somewhat and helps prevent and detect
interface breakage when more arguments are added.
</p>
-<SPAN class=""><PRE>
+<DIV class=""><PRE>
<span class="external"></span>def foo(a, b=1):
- <span class="external"> </span>...</PRE></SPAN>
-<SPAN class=""><PRE>Yes: <span class="external"></span>foo(1)
- <span class="external"></span>foo(1, b=2)</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>foo(1, 2)</PRE></SPAN>
+ <span class="external"> </span>...</PRE></DIV>
+<DIV class=""><PRE>Yes: <span class="external"></span>foo(1)
+ <span class="external"></span>foo(1, b=2)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>foo(1, 2)</PRE></DIV>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Properties" id="Properties">Properties</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Properties" id="Properties">Properties</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Properties__body','Properties__button')" name="Properties__button" id="Properties__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use properties for accessing or setting data where you would
normally have used simple, lightweight accessor or setter methods.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Properties__body" id="Properties__body" style="display: none"><SPAN class="link_button"><A href="?showone=Properties#Properties">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Properties__body" id="Properties__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Properties#Properties">
link
</A></SPAN>
<P class="">
@@ -746,7 +775,7 @@
by the property (using the Template Method DP).
</a></p>
- <SPAN class=""><PRE>Yes: <span class="external"></span>import math
+ <DIV class=""><PRE>Yes: <span class="external"></span>import math
<span class="external"></span>class Square(object):
<span class="external"> </span>"""A square with two properties: a writable area and a read-only perimeter.
@@ -790,16 +819,18 @@
<span class="external"> </span>def perimeter(self):
<span class="external"> </span>return self.side * 4
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="True/False_evaluations" id="True/False_evaluations">True/False evaluations</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="True/False_evaluations" id="True/False_evaluations">True/False evaluations</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('True/False_evaluations__body','True/False_evaluations__button')" name="True/False_evaluations__button" id="True/False_evaluations__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use the "implicit" false if at all possible.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="True/False_evaluations__body" id="True/False_evaluations__body" style="display: none"><SPAN class="link_button"><A href="?showone=True/False_evaluations#True/False_evaluations">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="True/False_evaluations__body" id="True/False_evaluations__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=True/False_evaluations#True/False_evaluations">
link
</A></SPAN>
<P class="">
@@ -853,22 +884,22 @@
benefit (i.e., accidentally handling <code>None</code> as 0). You may
compare a value which is known to be an integer (and is not the
result of <code>len()</code>) against the integer 0.
-<SPAN class=""><PRE>Yes: <span class="external"></span>if not users:
+<DIV class=""><PRE>Yes: <span class="external"></span>if not users:
<span class="external"> </span>print 'no users'
<span class="external"></span>if foo == 0:
<span class="external"> </span>self.handle_zero()
<span class="external"></span>if i % 10 == 0:
- <span class="external"> </span>self.handle_multiple_of_ten()</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>if len(users) == 0:
+ <span class="external"> </span>self.handle_multiple_of_ten()</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>if len(users) == 0:
<span class="external"> </span>print 'no users'
<span class="external"></span>if foo is not None and not foo:
<span class="external"> </span>self.handle_zero()
<span class="external"></span>if not i % 10:
- <span class="external"> </span>self.handle_multiple_of_ten()</PRE></SPAN>
+ <span class="external"> </span>self.handle_multiple_of_ten()</PRE></DIV>
</li>
<li>
@@ -876,18 +907,20 @@
evaluates to true.</li>
</ul>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Deprecated_Language_Features" id="Deprecated_Language_Features">Deprecated Language Features</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Deprecated_Language_Features" id="Deprecated_Language_Features">Deprecated Language Features</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Deprecated_Language_Features__body','Deprecated_Language_Features__button')" name="Deprecated_Language_Features__button" id="Deprecated_Language_Features__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use string methods instead of the <code>string</code> module
where possible. Use function call syntax instead
of <code>apply</code>. Use list comprehensions
and <code>for</code> loops instead of <code>filter</code>,
<code>map</code>, and <code>reduce</code>.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Deprecated_Language_Features__body" id="Deprecated_Language_Features__body" style="display: none"><SPAN class="link_button"><A href="?showone=Deprecated_Language_Features#Deprecated_Language_Features">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Deprecated_Language_Features__body" id="Deprecated_Language_Features__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Deprecated_Language_Features#Deprecated_Language_Features">
link
</A></SPAN>
<P class="">
@@ -900,25 +933,27 @@
We do not use any Python version which does not support
these features, so there is no reason not to use the new
styles.
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>words = string.split(foo, ':')
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>words = string.split(foo, ':')
<span class="external"></span>map(lambda x: x[1], filter(lambda x: x[2] == 5, my_list))
- <span class="external"></span>apply(fn, args, kwargs)</PRE></SPAN>
-<SPAN class=""><PRE>Yes: <span class="external"></span>words = foo.split(':')
+ <span class="external"></span>apply(fn, args, kwargs)</PRE></DIV>
+<DIV class=""><PRE>Yes: <span class="external"></span>words = foo.split(':')
<span class="external"></span>[x[1] for x in my_list if x[2] == 5]
- <span class="external"></span>fn(*args, **kwargs)</PRE></SPAN>
+ <span class="external"></span>fn(*args, **kwargs)</PRE></DIV>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Lexical_Scoping" id="Lexical_Scoping">Lexical Scoping</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Lexical_Scoping" id="Lexical_Scoping">Lexical Scoping</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lexical_Scoping__body','Lexical_Scoping__button')" name="Lexical_Scoping__button" id="Lexical_Scoping__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Okay to use.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Lexical_Scoping__body" id="Lexical_Scoping__body" style="display: none"><SPAN class="link_button"><A href="?showone=Lexical_Scoping#Lexical_Scoping">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Lexical_Scoping__body" id="Lexical_Scoping__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Lexical_Scoping#Lexical_Scoping">
link
</A></SPAN>
<P class="">
@@ -936,7 +971,7 @@
An example of the use of this feature is:
</p>
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>def get_adder(summand1):
<span class="external"> </span>"""Returns a function that adds numbers to a given number."""
<span class="external"> </span>def adder(summand2):
@@ -944,7 +979,7 @@
<span class="external"> </span>return adder
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
</P>
<P class="">
<SPAN class="stylepoint_section">Pros: </SPAN>
@@ -956,7 +991,7 @@
<SPAN class="stylepoint_section">Cons: </SPAN>
Can lead to confusing bugs. Such as this example based on
<a HREF="http://www.python.org/dev/peps/pep-0227/">PEP-0227</a>:
-<SPAN class=""><PRE class="badcode">
+<DIV class=""><PRE class="badcode">
<span class="external"></span>i = 4
<span class="external"></span>def foo(x):
<span class="external"> </span>def bar():
@@ -966,7 +1001,7 @@
<span class="external"> </span># ...
<span class="external"> </span>for i in x: # Ah, i *is* local to Foo, so this is what Bar sees
<span class="external"> </span>print i,
- <span class="external"> </span>bar()</PRE></SPAN>
+ <span class="external"> </span>bar()</PRE></DIV>
<p>
So <code>foo([1, 2, 3])</code> will print <code>1 2 3 3</code>, not
<code>1 2 3 4</code>.
@@ -976,14 +1011,16 @@
<SPAN class="stylepoint_section">Decision: </SPAN>
Okay to use.
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Function_and_Method_Decorators" id="Function_and_Method_Decorators">Function and Method Decorators</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Function_and_Method_Decorators" id="Function_and_Method_Decorators">Function and Method Decorators</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Function_and_Method_Decorators__body','Function_and_Method_Decorators__button')" name="Function_and_Method_Decorators__button" id="Function_and_Method_Decorators__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use decorators judiciously when there is a clear advantage.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Function_and_Method_Decorators__body" id="Function_and_Method_Decorators__body" style="display: none"><SPAN class="link_button"><A href="?showone=Function_and_Method_Decorators#Function_and_Method_Decorators">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Function_and_Method_Decorators__body" id="Function_and_Method_Decorators__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Function_and_Method_Decorators#Function_and_Method_Decorators">
link
</A></SPAN>
<P class="">
@@ -997,22 +1034,22 @@
static methods. However, the decorator syntax allows for
user-defined decorators as well. Specifically, for some function
<code>my_decorator</code>, this:
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>class C(object):
<span class="external"> </span>@my_decorator
<span class="external"> </span>def method(self):
<span class="external"> </span># method body ...
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
is equivalent to:
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>class C(object):
<span class="external"> </span>def method(self):
<span class="external"> </span># method body ...
<span class="external"> </span>method = my_decorator(method)
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
</P>
<P class="">
<SPAN class="stylepoint_section">Pros: </SPAN> Elegantly specifies some transformation on a method; the
@@ -1045,14 +1082,16 @@
<a HREF="#Main">main</a> for more discussion.
</p>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Threading" id="Threading">Threading</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Threading" id="Threading">Threading</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Threading__body','Threading__button')" name="Threading__button" id="Threading__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Do not rely on the atomicity of built-in types.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Threading__body" id="Threading__body" style="display: none"><SPAN class="link_button"><A href="?showone=Threading#Threading">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Threading__body" id="Threading__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Threading#Threading">
link
</A></SPAN>
<p>
@@ -1074,14 +1113,16 @@
<code>threading.Condition</code> instead of using lower-level
locks.
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Power_Features" id="Power_Features">Power Features</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Power_Features" id="Power_Features">Power Features</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Power_Features__body','Power_Features__button')" name="Power_Features__button" id="Power_Features__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Avoid these features.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Power_Features__body" id="Power_Features__body" style="display: none"><SPAN class="link_button"><A href="?showone=Power_Features#Power_Features">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Power_Features__body" id="Power_Features__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Power_Features#Power_Features">
link
</A></SPAN>
<P class="">
@@ -1108,27 +1149,32 @@
Avoid these features in
your code.
</P>
- </SPAN></SPAN>
- </SPAN>
- </SPAN>
- <SPAN class=""><H2 name="Python_Style_Rules" id="Python_Style_Rules">Python Style Rules</H2>
- <SPAN class=""><H3><A name="Semicolons" id="Semicolons">Semicolons</A></H3>
+ </DIV></DIV>
+ </DIV>
+ </DIV>
+ <DIV class="">
+<H2 name="Python_Style_Rules" id="Python_Style_Rules">Python Style Rules</H2>
+ <DIV class="">
+<H3><A name="Semicolons" id="Semicolons">Semicolons</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Semicolons__body','Semicolons__button')" name="Semicolons__button" id="Semicolons__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Do not terminate your lines with semi-colons and do not use
semi-colons to put two commands on the same line.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Semicolons__body" id="Semicolons__body" style="display: none"><SPAN class="link_button"><A href="?showone=Semicolons#Semicolons">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Semicolons__body" id="Semicolons__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Semicolons#Semicolons">
link
</A></SPAN>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Line_length" id="Line_length">Line length</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Line_length" id="Line_length">Line length</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Line_length__body','Line_length__button')" name="Line_length__button" id="Line_length__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Maximum line length is <em>80 characters</em>.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Line_length__body" id="Line_length__body" style="display: none"><SPAN class="link_button"><A href="?showone=Line_length#Line_length">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Line_length__body" id="Line_length__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Line_length#Line_length">
link
</A></SPAN>
<p>
@@ -1147,11 +1193,11 @@
</p>
- <SPAN class=""><PRE>Yes: foo_bar(self, width, height, color='black', design=None, x='foo',
+ <DIV class=""><PRE>Yes: foo_bar(self, width, height, color='black', design=None, x='foo',
emphasis=None, highlight=0)
if (width == 0 and height == 0 and
- color == 'red' and emphasis == 'strong'):</PRE></SPAN>
+ color == 'red' and emphasis == 'strong'):</PRE></DIV>
<p>
@@ -1159,9 +1205,9 @@
implicit line joining.
</p>
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>x = ('This will build a very long long '
-<span class="external"></span> 'long long long long long long string')</PRE></SPAN>
+<span class="external"></span> 'long long long long long long string')</PRE></DIV>
<p>
Make note of the indentation of the elements in the line
@@ -1169,14 +1215,16 @@
<a HREF="#indentation">indentation</a>
section for explanation.
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Parentheses" id="Parentheses">Parentheses</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Parentheses" id="Parentheses">Parentheses</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Parentheses__body','Parentheses__button')" name="Parentheses__button" id="Parentheses__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use parentheses sparingly.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Parentheses__body" id="Parentheses__body" style="display: none"><SPAN class="link_button"><A href="?showone=Parentheses#Parentheses">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Parentheses__body" id="Parentheses__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Parentheses#Parentheses">
link
</A></SPAN>
<p>
@@ -1185,7 +1233,7 @@
It is however fine to use parentheses around tuples.
</p>
-<SPAN class=""><PRE>Yes: <span class="external"></span>if foo:
+<DIV class=""><PRE>Yes: <span class="external"></span>if foo:
<span class="external"> </span>bar()
<span class="external"></span>while x:
<span class="external"> </span>x = bar()
@@ -1194,20 +1242,22 @@
<span class="external"></span>if not x:
<span class="external"> </span>bar()
<span class="external"></span>return foo
- <span class="external"></span>for (x, y) in dict.items(): ...</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>if (x):
+ <span class="external"></span>for (x, y) in dict.items(): ...</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>if (x):
<span class="external"> </span>bar()
<span class="external"></span>if not(x):
<span class="external"> </span>bar()
- <span class="external"></span>return (foo)</PRE></SPAN>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Indentation" id="Indentation">Indentation</A></H3>
+ <span class="external"></span>return (foo)</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Indentation" id="Indentation">Indentation</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Indentation__body','Indentation__button')" name="Indentation__button" id="Indentation__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Indent your code blocks with <em>4 spaces</em>.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Indentation__body" id="Indentation__body" style="display: none"><SPAN class="link_button"><A href="?showone=Indentation#Indentation">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Indentation__body" id="Indentation__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Indentation#Indentation">
link
</A></SPAN>
<p>
@@ -1220,31 +1270,33 @@
</p>
-<SPAN class=""><PRE>Yes: # Aligned with opening delimiter
+<DIV class=""><PRE>Yes: # Aligned with opening delimiter
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 4-space hanging indent; nothing on first line
foo = long_function_name(
var_one, var_two, var_three,
- var_four)</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span># Stuff on first line forbidden
+ var_four)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span># Stuff on first line forbidden
<span class="external"></span>foo = long_function_name(var_one, var_two,
<span class="external"></span> var_three, var_four)
<span class="external"></span># 2-space hanging indent forbidden
<span class="external"></span>foo = long_function_name(
<span class="external"></span> var_one, var_two, var_three,
- <span class="external"></span> var_four)</PRE></SPAN>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Blank_Lines" id="Blank_Lines">Blank Lines</A></H3>
+ <span class="external"></span> var_four)</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Blank_Lines" id="Blank_Lines">Blank Lines</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Blank_Lines__body','Blank_Lines__button')" name="Blank_Lines__button" id="Blank_Lines__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Two blank lines between top-level definitions, one blank line
between method definitions.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Blank_Lines__body" id="Blank_Lines__body" style="display: none"><SPAN class="link_button"><A href="?showone=Blank_Lines#Blank_Lines">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Blank_Lines__body" id="Blank_Lines__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Blank_Lines#Blank_Lines">
link
</A></SPAN>
<p>
@@ -1254,41 +1306,43 @@
Use single blank lines as you judge appropriate within functions or
methods.
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Whitespace" id="Whitespace">Whitespace</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Whitespace" id="Whitespace">Whitespace</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Whitespace__body','Whitespace__button')" name="Whitespace__button" id="Whitespace__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Follow standard typographic rules for the use of spaces around
punctuation.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Whitespace__body" id="Whitespace__body" style="display: none"><SPAN class="link_button"><A href="?showone=Whitespace#Whitespace">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Whitespace__body" id="Whitespace__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Whitespace#Whitespace">
link
</A></SPAN>
<p>
No whitespace inside parentheses, brackets or braces.
</p>
-<SPAN class=""><PRE>Yes: <span class="external"></span>spam(ham[1], {eggs: 2}, [])</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>spam( ham[ 1 ], { eggs: 2 }, [ ] )</PRE></SPAN>
+<DIV class=""><PRE>Yes: <span class="external"></span>spam(ham[1], {eggs: 2}, [])</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>spam( ham[ 1 ], { eggs: 2 }, [ ] )</PRE></DIV>
<p>
No whitespace before a comma, semicolon, or colon. Do use
whitespace after a comma, semicolon, or colon except at the end
of the line.
</p>
-<SPAN class=""><PRE>Yes: <span class="external"></span>if x == 4:
+<DIV class=""><PRE>Yes: <span class="external"></span>if x == 4:
<span class="external"> </span>print x, y
- <span class="external"></span>x, y = y, x</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>if x == 4 :
+ <span class="external"></span>x, y = y, x</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>if x == 4 :
<span class="external"> </span>print x , y
- <span class="external"></span>x , y = y , x</PRE></SPAN>
+ <span class="external"></span>x , y = y , x</PRE></DIV>
<p>
No whitespace before the open paren/bracket that starts an argument list,
indexing or slicing.
</p>
- <SPAN class=""><PRE>Yes: <span class="external"></span>spam(1)</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>spam (1)</PRE></SPAN>
-<SPAN class=""><PRE>Yes: <span class="external"></span>dict['key'] = list[index]</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>dict ['key'] = list [index]</PRE></SPAN>
+ <DIV class=""><PRE>Yes: <span class="external"></span>spam(1)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>spam (1)</PRE></DIV>
+<DIV class=""><PRE>Yes: <span class="external"></span>dict['key'] = list[index]</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>dict ['key'] = list [index]</PRE></DIV>
<p>
Surround binary operators with a single space on either side for
@@ -1298,48 +1352,50 @@
insertion of spaces around arithmetic operators but always be
consistent about whitespace on either side of a binary operator.
</p>
-<SPAN class=""><PRE>Yes: <span class="external"></span>x == 1</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>x<1</PRE></SPAN>
+<DIV class=""><PRE>Yes: <span class="external"></span>x == 1</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>x<1</PRE></DIV>
<p>
Don't use spaces around the '=' sign when used to indicate a
keyword argument or a default parameter value.
</p>
-<SPAN class=""><PRE>Yes: <span class="external"></span>def complex(real, imag=0.0): return magic(r=real, i=imag)</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>def complex(real, imag = 0.0): return magic(r = real, i = imag)</PRE></SPAN>
+<DIV class=""><PRE>Yes: <span class="external"></span>def complex(real, imag=0.0): return magic(r=real, i=imag)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>def complex(real, imag = 0.0): return magic(r = real, i = imag)</PRE></DIV>
<p>
Don't use spaces to vertically align tokens on consecutive lines, since it
becomes a maintenance burden (applies to <code>:</code>, <code>#</code>,
<code>=</code>, etc.):
</p>
-<SPAN class=""><PRE>Yes:
+<DIV class=""><PRE>Yes:
foo = 1000 # comment
long_name = 2 # comment that should not be aligned
dictionary = {
"foo": 1,
"long_name": 2,
- }</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No:
+ }</PRE></DIV>
+<DIV class=""><PRE class="badcode">No:
foo = 1000 # comment
long_name = 2 # comment that should not be aligned
dictionary = {
"foo" : 1,
"long_name": 2,
- }</PRE></SPAN>
+ }</PRE></DIV>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Python_Interpreter" id="Python_Interpreter">Python Interpreter</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Python_Interpreter" id="Python_Interpreter">Python Interpreter</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Python_Interpreter__body','Python_Interpreter__button')" name="Python_Interpreter__button" id="Python_Interpreter__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Modules should begin with
<code>#!/usr/bin/env python<version></code>
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Python_Interpreter__body" id="Python_Interpreter__body" style="display: none"><SPAN class="link_button"><A href="?showone=Python_Interpreter#Python_Interpreter">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Python_Interpreter__body" id="Python_Interpreter__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Python_Interpreter#Python_Interpreter">
link
</A></SPAN>
<p>
@@ -1347,8 +1403,8 @@
interpreter used to execute the program:
</p>
-<SPAN class=""><PRE>
-<span class="external"></span>#!/usr/bin/env python2.4</PRE></SPAN>
+<DIV class=""><PRE>
+<span class="external"></span>#!/usr/bin/env python2.4</PRE></DIV>
<p>
Always use the most specific version you can use, e.g.,
@@ -1362,15 +1418,17 @@
2.3.0?
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Comments" id="Comments">Comments</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Comments" id="Comments">Comments</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Comments__body','Comments__button')" name="Comments__button" id="Comments__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Be sure to use the right style for module, function, method and in-line
comments.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Comments__body" id="Comments__body" style="display: none"><SPAN class="link_button"><A href="?showone=Comments#Comments">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Comments__body" id="Comments__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Comments#Comments">
link
</A></SPAN>
@@ -1433,7 +1491,7 @@
functions should use "Yields:" rather than "Returns:".
</p>
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
<span class="external"> </span>"""Fetches rows from a Bigtable.
@@ -1465,7 +1523,7 @@
<span class="external"> </span>"""
<span class="external"> </span>pass
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
</P>
<P class="">
<SPAN class="stylepoint_subsection">Classes</SPAN>
@@ -1477,7 +1535,7 @@
function's Args section.
</p>
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>class SampleClass(object):
<span class="external"> </span>"""Summary of class here.
@@ -1497,7 +1555,7 @@
<span class="external"> </span>def public_method(self):
<span class="external"> </span>"""Performs operation blah."""
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
</P>
<P class="">
@@ -1512,7 +1570,7 @@
commence. Non-obvious ones get comments at the end of the line.
</p>
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span># We use a weighted dictionary search to find out where i is in
<span class="external"></span># the array. We extrapolate position based on the largest num
<span class="external"></span># in the array and the array size and then do binary search to
@@ -1520,7 +1578,7 @@
<span class="external"></span>if i & (i-1) == 0: # true iff i is a power of 2
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
<p>
To improve legibility, these comments should be at least 2 spaces away
@@ -1533,25 +1591,27 @@
do) better than you do.
</p>
- <SPAN class=""><PRE class="badcode">
+ <DIV class=""><PRE class="badcode">
<span class="external"></span># BAD COMMENT: Now go through the b array and make sure whenever i occurs
<span class="external"></span># the next element is i+1
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Classes" id="Classes">Classes</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Classes" id="Classes">Classes</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Classes__body','Classes__button')" name="Classes__button" id="Classes__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
If a class inherits from no other base classes, explicitly inherit
from <code>object</code>. This also applies to nested classes.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Classes__body" id="Classes__body" style="display: none"><SPAN class="link_button"><A href="?showone=Classes#Classes">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Classes__body" id="Classes__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Classes#Classes">
link
</A></SPAN>
- <SPAN class=""><PRE class="badcode">No: <span class="external"></span>class SampleClass:
+ <DIV class=""><PRE class="badcode">No: <span class="external"></span>class SampleClass:
<span class="external"> </span>pass
@@ -1560,9 +1620,9 @@
<span class="external"> </span>class InnerClass:
<span class="external"> </span>pass
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
- <SPAN class=""><PRE>Yes: <span class="external"></span>class SampleClass(object):
+ <DIV class=""><PRE>Yes: <span class="external"></span>class SampleClass(object):
<span class="external"> </span>pass
@@ -1575,7 +1635,7 @@
<span class="external"></span>class ChildClass(ParentClass):
<span class="external"> </span>"""Explicitly inherits from another class already."""
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
<p>Inheriting from <code>object</code> is needed to make properties work
properly, and it will protect your code from one particular potential
@@ -1585,24 +1645,26 @@
<code>__getattribute__</code>, <code>__setattr__</code>,
<code>__hash__</code>, <code>__repr__</code>, and <code>__str__</code>.
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Strings" id="Strings">Strings</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Strings" id="Strings">Strings</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Strings__body','Strings__button')" name="Strings__button" id="Strings__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use the <code>%</code> operator for formatting strings,
even when the parameters are all strings. Use your best judgement
to decide between <code>+</code> and <code>%</code> though.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Strings__body" id="Strings__body" style="display: none"><SPAN class="link_button"><A href="?showone=Strings#Strings">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Strings__body" id="Strings__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Strings#Strings">
link
</A></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>x = '%s%s' % (a, b) # use + in this case
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>x = '%s%s' % (a, b) # use + in this case
<span class="external"></span>x = imperative + ', ' + expletive + '!'
- <span class="external"></span>x = 'name: ' + name + '; score: ' + str(n)</PRE></SPAN>
-<SPAN class=""><PRE>Yes: <span class="external"></span>x = a + b
+ <span class="external"></span>x = 'name: ' + name + '; score: ' + str(n)</PRE></DIV>
+<DIV class=""><PRE>Yes: <span class="external"></span>x = a + b
<span class="external"></span>x = '%s, %s!' % (imperative, expletive)
- <span class="external"></span>x = 'name: %s; score: %d' % (name, n)</PRE></SPAN>
+ <span class="external"></span>x = 'name: %s; score: %d' % (name, n)</PRE></DIV>
<p>
Avoid using the <code>+</code> and <code>+=</code> operators to
@@ -1613,15 +1675,15 @@
substring to a <code>cStringIO.StringIO</code> buffer).
</p>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>employee_table = '<table>'
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>employee_table = '<table>'
<span class="external"></span>for last_name, first_name in employee_list:
<span class="external"> </span>employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
- <span class="external"></span>employee_table += '</table>'</PRE></SPAN>
-<SPAN class=""><PRE>Yes: <span class="external"></span>items = ['<table>']
+ <span class="external"></span>employee_table += '</table>'</PRE></DIV>
+<DIV class=""><PRE>Yes: <span class="external"></span>items = ['<table>']
<span class="external"></span>for last_name, first_name in employee_list:
<span class="external"> </span>items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
<span class="external"></span>items.append('</table>')
- <span class="external"></span>employee_table = ''.join(items)</PRE></SPAN>
+ <span class="external"></span>employee_table = ''.join(items)</PRE></DIV>
<p>
Use <code>"""</code> for multi-line strings rather than
@@ -1630,23 +1692,25 @@
not flow with the indentation of the rest of the program:
</p>
- <SPAN class=""><PRE class="badcode"> No<span class="external"></span>:
+ <DIV class=""><PRE class="badcode"> No<span class="external"></span>:
<span class="external"></span>print """This is pretty ugly.
Don'<span class="external"></span>t do this.
"""<span class="external"></span>
-</PRE></SPAN>
-<SPAN class=""><PRE>Ye<span class="external"></span>s:
+</PRE></DIV>
+<DIV class=""><PRE>Ye<span class="external"></span>s:
<span class="external"></span>print ("This is much nicer.\n"
- <span class="external"></span> "Do it this way.\n")</PRE></SPAN>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="TODO_Comments" id="TODO_Comments">TODO Comments</A></H3>
+ <span class="external"></span> "Do it this way.\n")</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="TODO_Comments" id="TODO_Comments">TODO Comments</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('TODO_Comments__body','TODO_Comments__button')" name="TODO_Comments__button" id="TODO_Comments__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Use <code>TODO</code> comments for code that is temporary, a
short-term solution, or good-enough but not perfect.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none"><SPAN class="link_button"><A href="?showone=TODO_Comments#TODO_Comments">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=TODO_Comments#TODO_Comments">
link
</A></SPAN>
<p>
@@ -1662,31 +1726,33 @@
<code>TODO</code> is not a commitment to provide the fix yourself.
</p>
- <SPAN class=""><PRE># TODO(kl@gmail.com): Drop the use of "has_key".
-# TODO(Zeke) change this to use relations.</PRE></SPAN>
+ <DIV class=""><PRE># TODO(kl@gmail.com): Drop the use of "has_key".
+# TODO(Zeke) change this to use relations.</PRE></DIV>
<p>
If your <code>TODO</code> is of the form "At a future date do
something" make sure that you either include a very specific
date ("Fix by November 2009") or a very specific event
("Remove this code when all clients can handle XML responses.").
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Imports_formatting" id="Imports_formatting">Imports formatting</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Imports_formatting" id="Imports_formatting">Imports formatting</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports_formatting__body','Imports_formatting__button')" name="Imports_formatting__button" id="Imports_formatting__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Imports should be on separate lines.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Imports_formatting__body" id="Imports_formatting__body" style="display: none"><SPAN class="link_button"><A href="?showone=Imports_formatting#Imports_formatting">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Imports_formatting__body" id="Imports_formatting__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Imports_formatting#Imports_formatting">
link
</A></SPAN>
<p>
E.g.:
</p>
-<SPAN class=""><PRE>Yes: <span class="external"></span>import os
- <span class="external"></span>import sys</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No: <span class="external"></span>import os, sys</PRE></SPAN>
+<DIV class=""><PRE>Yes: <span class="external"></span>import os
+ <span class="external"></span>import sys</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>import os, sys</PRE></DIV>
<p>
Imports are always put at the top of the file, just after any
module comments and doc strings and before module globals and
@@ -1703,22 +1769,25 @@
Within each grouping, imports should be sorted lexicographically,
ignoring case, according to each module's full package path.
</p>
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>import foo
<span class="external"></span>from foo import bar
<span class="external"></span>from foo.bar import baz
<span class="external"></span>from foo.bar import Quux
-<span class="external"></span>from Foob import ar</PRE></SPAN>
+<span class="external"></span>from Foob import ar</PRE></DIV>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Statements" id="Statements">Statements</A></H3>
+
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Statements" id="Statements">Statements</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Statements__body','Statements__button')" name="Statements__button" id="Statements__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Generally only one statement per line.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Statements__body" id="Statements__body" style="display: none"><SPAN class="link_button"><A href="?showone=Statements#Statements">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Statements__body" id="Statements__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Statements#Statements">
link
</A></SPAN>
<p>
@@ -1731,10 +1800,10 @@
there is no <code>else</code>.
</p>
- <SPAN class=""><PRE>Ye<span class="external"></span>s:
+ <DIV class=""><PRE>Ye<span class="external"></span>s:
- <span class="external"></span>if foo: bar(foo)</PRE></SPAN>
-<SPAN class=""><PRE class="badcode">No<span class="external"></span>:
+ <span class="external"></span>if foo: bar(foo)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No<span class="external"></span>:
<span class="external"></span>if foo: bar(foo)
<span class="external"></span>else: baz(foo)
@@ -1746,18 +1815,20 @@
<span class="external"> </span>bar(foo)
<span class="external"></span>except ValueError: baz(foo)
<span class="external"></span>
-</PRE></SPAN>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Access_Control" id="Access_Control">Access Control</A></H3>
+</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Access_Control" id="Access_Control">Access Control</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Access_Control__body','Access_Control__button')" name="Access_Control__button" id="Access_Control__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
If an accessor function would be trivial you should use public variables
instead of accessor functions to avoid the extra cost of function
calls in Python. When more functionality is added you can use
<code>property</code> to keep the syntax consistent.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Access_Control__body" id="Access_Control__body" style="display: none"><SPAN class="link_button"><A href="?showone=Access_Control#Access_Control">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Access_Control__body" id="Access_Control__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Access_Control#Access_Control">
link
</A></SPAN>
<p>
@@ -1769,16 +1840,18 @@
code still attempting to access the variable by the old method should
break visibly so they are made aware of the change in complexity.
</p>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Naming" id="Naming">Naming</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Naming" id="Naming">Naming</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Naming__body','Naming__button')" name="Naming__button" id="Naming__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
<code>module_name, package_name, ClassName, method_name, ExceptionName,
function_name, GLOBAL_VAR_NAME, instance_var_name,
function_parameter_name, local_var_name.</code>
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Naming__body" id="Naming__body" style="display: none"><SPAN class="link_button"><A href="?showone=Naming#Naming">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Naming__body" id="Naming__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Naming#Naming">
link
</A></SPAN>
<P class="">
@@ -1909,17 +1982,19 @@
</P>
- </SPAN></SPAN>
- </SPAN>
- <SPAN class=""><H3><A name="Main" id="Main">Main</A></H3>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Main" id="Main">Main</A></H3>
<SPAN class="showhide_button" onclick="javascript:ShowHideByName('Main__body','Main__button')" name="Main__button" id="Main__button">▶</SPAN>
- <SPAN class="">
+ <DIV style="display:inline;" class="">
Even a file meant to be used as a script should be importable and a
mere import should not have the side effect of executing the script's
main functionality. The main functionality should be in a main()
function.
- </SPAN>
- <SPAN class=""><BR><SPAN class="stylepoint_body" name="Main__body" id="Main__body" style="display: none"><SPAN class="link_button"><A href="?showone=Main#Main">
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Main__body" id="Main__body" style="display: none">
+<SPAN class="link_button"><A href="?showone=Main#Main">
link
</A></SPAN>
<p>
@@ -1938,14 +2013,14 @@
- <SPAN class=""><PRE>
+ <DIV class=""><PRE>
<span class="external"></span>def main():
<span class="external"> </span>...
<span class="external"></span>if __name__ == '__main__':
<span class="external"> </span>main()
<span class="external"></span>
-</PRE></SPAN>
+</PRE></DIV>
<p>
All code at the top level will be executed when the module is
@@ -1953,9 +2028,9 @@
perform other operations that should not be executed when the
file is being <code>pycheck</code>ed or <code>pydoc</code>ed.
</p>
- </SPAN></SPAN>
- </SPAN>
- </SPAN>
+ </DIV></DIV>
+ </DIV>
+ </DIV>
<H2>Parting Words</H2>
<p>
@@ -1983,7 +2058,7 @@
<p align="right">
-Revision 2.14
+Revision 2.15
</p>