StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Update C++ style guide to 3.199:

Browse Source 
- Update an example to omit the blank line between C and C++ #includes.
 - Rewrite the paragraph about #include ordering.
 - Clarify namespace closing comments.
 - Discourage const references for input arguments which are aliased beyond
   the scope of the function call.
 - Replace all '&' with '&'.
 - Clarify that interfaces must have virtual destructors.
 - Add an explicit example for |else if|.
 - C++11 updates.

Update Objective-C style guide to 2.36:
 - Remove requirement to list @dynamic implementations.
 - Remove requirement to never synthesize CFType properties, since they may
   be retained on 10.6.
 - Use __weak and __strong type declaration modifiers rather than comments.
 - Make the copyright/license information consistent.
 - An example initializer comment revealed too much about the implementation.
 - Correct spelling mistakes.
 - Fix names that didn't follow Cocoa conventions.
 - Fix examples to conform to style.
 - Add a section about no braces for empty interfaces.
 - Add a section about automatically synthesized instance variables.
 - Codify avoidance of accessors in -init and -dealloc methods.
 - Changes for the 80-column rule.
 - Weaken the language around object ownership type qualifiers.
 - Document the rules for formatting blocks.

Update JavaScript style guide to 2.27:
 - Introduce EcmaScript 5 Strict verbiage.
 - Add a note about private constructors.
 - Simplify explanations about JSDoc comments.
 - Sort the JSDoc tags.
 - Remove the sections about type-checking now that the JSDoc tags and JS
   types are no longer one table.
 - Convert <tt> to <code>, because the XSL processor eats <tt>.
 - Add @suppress.
 - Mark @inheritDoc deprecated in favor of @override.
 - Add a section about inner classes and enums being defined in the same file
   as the top-level class they are defined on.

Update Python style guide to 2.28:
 - Change "Naming" summary to match body.
 - Make the prohibition against backslash line continuation explicit.
 - Update the TODO section to match the C++ style guide.
 - Declare Python code without a shebang line to be stylish.
 - Clarify rules on function docstrings.
 - Fix spelling errors.
 - Update with styleguide.xsl 1.33.

Update styleguide.xsl to 1.33:
 - Clean up style guide JS.
 - Links to anchor tags auto-expand.
This commit is contained in:
mark@chromium.org 2011-11-04 16:55:22 +00:00
parent 8a95ecca27
commit e33361fcd3
5 changed files with 1432 additions and 1212 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
cppguide.xml
View File

@ -4,7 +4,7 @@
<p align="right">
Revision 3.188
Revision 3.199
</p>
@ -209,7 +209,6 @@ Tashana Landray
definitions of the classes they use, and usually have to
include several header files.
</p>
<SUBSECTION title="Note:">
If you use a symbol <code>Foo</code> in your source file, you
should bring in a definition for <code>Foo</code> yourself,
@ -383,11 +382,13 @@ Tashana Landray
<code>.h</code> files.</li>
</ol>
<p>
The preferred ordering reduces hidden dependencies. We want
every header file to be compilable on its own. The easiest
way to achieve this is to make sure that every one of them is
the first <code>.h</code> file <code>#include</code>d in some
<code>.cc</code>.
With the preferred ordering, if <code><var>dir/foo2</var>.h</code>
omits any necessary includes, the build of
<code><var>dir/foo</var>.cc</code> or
<code><var>dir/foo</var>_test.cc</code> will break.
Thus, this rule ensures that build breaks show up first
for the people working on these files, not for innocent people
in other packages.
</p>
<p>
<code><var>dir/foo</var>.cc</code> and
@ -412,7 +413,6 @@ Tashana Landray
#include &lt;sys/types.h&gt;
#include &lt;unistd.h&gt;
#include &lt;hash_map&gt;
#include &lt;vector&gt;
@ -468,6 +468,7 @@ Tashana Landray
<DECISION>
<p>
Use namespaces according to the policy described below.
Terminate namespaces with comments as shown in the given examples.
</p>
<SUBSECTION title="Unnamed Namespaces">
@ -490,9 +491,7 @@ Tashana Landray
associated with a particular class may be declared
in that class as types, static data members or
static member functions rather than as members of
an unnamed namespace. Terminate the unnamed
namespace as shown, with a comment <code>//
namespace</code>.
an unnamed namespace.
</p>
</li>
<li> Do not use unnamed namespaces in <code>.h</code>
@ -1239,7 +1238,7 @@ Tashana Landray
An interface class can never be directly instantiated
because of the pure virtual method(s) it declares. To make
sure all implementations of the interface can be destroyed
correctly, they must also declare a virtual destructor (in
correctly, the interface must also declare a virtual destructor (in
an exception to the first rule, this should not be pure). See
Stroustrup, <cite>The C++ Programming Language</cite>, 3rd
edition, section 12.4 for details.
@ -1574,14 +1573,24 @@ Tashana Landray
non-<code>const</code> reference parameters.
</p>
<p>
One case when you might want an input parameter to be a
<code>const</code> pointer is if you want to emphasize that the
argument is not copied, so it must exist for the lifetime of the
object; it is usually best to document this in comments as
well. STL adapters such as <code>bind2nd</code> and
<code>mem_fun</code> do not permit reference parameters, so
you must declare functions with pointer parameters in these
cases, too.
However, there are some instances where using <code>const T*</code>
is preferable to <code>const T&amp;</code> for input parameters. For
example:
You want to pass in NULL.
The function saves a pointer or reference to the input.
Remember that most of the time input parameters are going to be
specified as <code>const T&amp;</code>. Using <code>const T*</code>
instead communicates to the reader that the input is somehow treated
differently. So if you choose <code>const T*</code> rather than
<code>const T&amp;</code>, do so for a concrete reason; otherwise it
will likely confuse readers by making them look for an explanation
that doesn't exist.
</p>
</DECISION>
</BODY>
@ -2606,28 +2615,29 @@ Tashana Landray
</BODY>
</STYLEPOINT>
<STYLEPOINT title="C++0x">
<STYLEPOINT title="C++11">
<SUMMARY>
Use only approved libraries and language extensions from C++0x.
Use only approved libraries and language extensions from C++11 (formerly
known as C++0x).
Currently, none are approved.
</SUMMARY>
<BODY>
<DEFINITION>
C++0x is the next ISO C++ standard, currently in
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3092.pdf">final
committee draft</a> form. It contains
<a href="http://en.wikipedia.org/wiki/C%2B%2B0x">significant
C++11 is the latest ISO C++ standard.
It contains
<a href="http://en.wikipedia.org/wiki/C%2B%2B11">significant
changes</a> both to the language and libraries.
</DEFINITION>
<PROS>
We expect that C++0x will become the next standard, and eventually will
C++11 has become the official standard, and eventually will
be supported by most C++ compilers. It standardizes some common C++
extensions that we use already, allows shorthands for some operations,
and has some safety improvements.
and has some performance and safety improvements.
</PROS>
<CONS>
<p>
The C++0x standard is substantialy more complex than its predecessor
The C++11 standard is substantially more complex than its predecessor
(1,300 pages versus 800 pages), and is
unfamilar to many developers. The long-term effects of some
features on code readability and maintenance are unknown. We cannot
@ -2635,7 +2645,7 @@ Tashana Landray
tools that may be of interest (gcc, icc, clang, Eclipse, etc.).
</p>
<p>
As with <a href="#Boost">Boost</a>, some C++0x extensions encourage
As with <a href="#Boost">Boost</a>, some C++11 extensions encourage
coding practices that hamper readability&#8212;for example by removing
checked redundancy (such as type names) that may be helpful to readers,
or by encouraging template metaprogramming. Other extensions
@ -2645,9 +2655,12 @@ Tashana Landray
</p>
</CONS>
<DECISION>
Use only C++0x libraries and language features that have been approved
Use only C++11 libraries and language features that have been approved
for use. Currently, no such features are approved.
Features will be approved individually as appropriate.
Avoid writing code that is incompatible with C++11 (even though it
works in C++03).
</DECISION>
</BODY>
</STYLEPOINT>
@ -3845,7 +3858,9 @@ Tashana Landray
<CODE_SNIPPET>
if (condition) { // no spaces inside parentheses
... // 2 space indent.
} else { // The else goes on the same line as the closing brace.
} else if (...) { // The else goes on the same line as the closing brace.
...
} else {
...
}
</CODE_SNIPPET>
@ -4069,7 +4084,7 @@ Tashana Landray
the <code>&amp;&amp;</code> logical AND operators are at the
end of the line. This is more common in Google code, though
wrapping all operators at the beginning of the line is also
allowed. Feel free to insert extra parentheses judiciously,
allowed. Feel free to insert extra parentheses judiciously
because they can be very helpful in increasing readability
when used appropriately. Also note that you should always use the
punctuation operators, such as <code>&amp;&amp;</code> and
@ -4550,7 +4565,7 @@ Tashana Landray
<HR/>
<p align="right">
Revision 3.188
Revision 3.199
</p>

1647
javascriptguide.xml
View File

File diff suppressed because it is too large Load Diff

387
objcguide.xml
View File

@ -4,7 +4,7 @@
<p align="right">
Revision 2.24
Revision 2.36
</p>
@ -129,8 +129,8 @@ Revision 2.24
</p>
<CODE_SNIPPET>
// GTMFoo.h
// FooProject
// Foo.h
// AwesomeProject
//
// Created by Greg Miller on 6/13/08.
// Copyright 2008 Google, Inc. All rights reserved.
@ -144,26 +144,27 @@ Revision 2.24
// documenting.
//
// (no blank line between this comment and the interface)
@interface GTMFoo : NSObject {
@interface Foo : NSObject {
@private
NSString *foo_;
NSString *bar_;
NSString *bam_;
}
// Returns an autoreleased instance of GMFoo. See -initWithString: for details
// about the argument.
+ (id)fooWithString:(NSString *)string;
// Returns an autoreleased instance of Foo. See -initWithBar: for details
// about |bar|.
+ (id)fooWithBar:(NSString *)bar;
// Designated initializer. |string| will be copied and assigned to |foo_|.
- (id)initWithString:(NSString *)string;
// Designated initializer. |bar| is a thing that represents a thing that
// does a thing.
- (id)initWithBar:(NSString *)bar;
// Gets and sets the string for |foo_|.
- (NSString *)foo;
- (void)setFoo:(NSString *)newFoo;
// Gets and sets |bar_|.
- (NSString *)bar;
- (void)setBar:(NSString *)bar;
// Does some work on |blah| and returns YES if the work was completed
// successfuly, and NO otherwise.
- (BOOL)doWorkWithString:(NSString *)blah;
// Does some work with |blah| and returns YES if the work was completed
// successfully, and NO otherwise.
- (BOOL)doWorkWithBlah:(NSString *)blah;
@end
</CODE_SNIPPET>
@ -177,51 +178,51 @@ Revision 2.24
<CODE_SNIPPET>
//
// GTMFoo.m
// FooProject
// Foo.m
// AwesomeProject
//
// Created by Greg Miller on 6/13/08.
// Copyright 2008 Google, Inc. All rights reserved.
//
#import "GTMFoo.h"
#import "Foo.h"
@implementation GTMFoo
@implementation Foo
+ (id)fooWithString:(NSString *)string {
return [[[self alloc] initWithString:string] autorelease];
+ (id)fooWithBar:(NSString *)bar {
return [[[self alloc] initWithBar:bar] autorelease];
}
// Must always override super's designated initializer.
- (id)init {
return [self initWithString:nil];
return [self initWithBar:nil];
}
- (id)initWithString:(NSString *)string {
- (id)initWithBar:(NSString *)bar {
if ((self = [super init])) {
foo_ = [string copy];
bar_ = [[NSString alloc] initWithFormat:@"hi %d", 3];
bar_ = [bar copy];
bam_ = [[NSString alloc] initWithFormat:@"hi %d", 3];
}
return self;
}
- (void)dealloc {
[foo_ release];
[bar_ release];
[bam_ release];
[super dealloc];
}
- (NSString *)foo {
return foo_;
- (NSString *)bar {
return bar_;
}
- (void)setFoo:(NSString *)newFoo {
[foo_ autorelease];
foo_ = [newFoo copy];
- (void)setBar:(NSString *)bar {
[bar_ autorelease];
bar_ = [bar copy];
}
- (BOOL)doWorkWithString:(NSString *)blah {
- (BOOL)doWorkWithBlah:(NSString *)blah {
// ...
return NO;
}
@ -232,7 +233,7 @@ Revision 2.24
<p>
Blank lines before and after <code>@interface</code>,
<code>@implementation</code>, and <code>@end</code> are optional. If your
<code>@interface</code> declares instance variables, as most do, any blank
<code>@interface</code> declares instance variables, a blank
line should come after the closing brace (<code>}</code>).
<p>
</p>
@ -260,14 +261,19 @@ Revision 2.24
<STYLEPOINT title="Line Length">
<SUMMARY>
Each line of text in your code should be at most 80 characters long.
Each line of text in your code should try to be at most 80 characters
long.
</SUMMARY>
<BODY>
<p>
Even though Objective-C tends to be a more verbose language than C++,
to aid in the interoperability with that guide, we have decided
to keep the limit at 80 columns as well. It's easier to live with
than you might expect.
Strive to keep your code within 80 columns. We realize that Objective C
is a verbose language and in some cases it may be more readable to
extend slightly beyond 80 columns, but this should definitely be the
exception and not commonplace.
</p>
<p>
If a reviewer asks that you reformat a line because they feel it can be
fit in 80 columns and still be readable, you should do so.
</p>
<p>
@ -435,7 +441,7 @@ Revision 2.24
<BODY>
<p>
This applies to class declarations, instance variables, and method
delcarations. For example:
declarations. For example:
</p>
<CODE_SNIPPET>
@interface MyProtocoledClass : NSObject&lt;NSWindowDelegate&gt; {
@ -448,6 +454,92 @@ Revision 2.24
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Blocks">
<SUMMARY>
Blocks are preferred to the target-selector pattern when creating
callbacks, as it makes code easier to read. Code inside blocks should be
indented four spaces.
</SUMMARY>
<BODY>
<p>
There are several appropriate style rules, depending on how long the
block is:
</p>
<ul>
<li>If the block can fit on one line, no wrapping is necessary.</li>
<li>
If it has to wrap, the closing brace should line up with the first
character of the line on which the block is declared.
</li>
<li>Code within the block should be indented four spaces.</li>
<li>
If the block is large, e.g. more than 20 lines, it is recommended to
move it out-of-line into a local variable.
</li>
<li>
If the block takes no parameters, there are no spaces between the
characters <code>^{</code>. If the block takes parameters, there is no
space between the <code>^(</code> characters, but there is one space
between the <code>) {</code> characters.
</li>
<li>
Two space indents inside blocks are also allowed, but should only
be used when it's consistent with the rest of the project's code.
</li>
</ul>
<CODE_SNIPPET>
// The entire block fits on one line.
[operation setCompletionBlock:^{ [self onOperationDone]; }];
// The block can be put on a new line, indented four spaces, with the
// closing brace aligned with the first character of the line on which
// block was declared.
[operation setCompletionBlock:^{
[self.delegate newDataAvailable];
}];
// Using a block with a C API follows the same alignment and spacing
// rules as with Objective-C.
dispatch_async(fileIOQueue_, ^{
NSString* path = [self sessionFilePath];
if (path) {
// ...
}
});
// An example where the parameter wraps and the block declaration fits
// on the same line. Note the spacing of |^(SessionWindow *window) {|
// compared to |^{| above.
[[SessionService sharedService]
loadWindowWithCompletionBlock:^(SessionWindow *window) {
if (window) {
[self windowDidLoad:window];
} else {
[self errorLoadingWindow];
}
}];
// An example where the parameter wraps and the block declaration does
// not fit on the same line as the name.
[[SessionService sharedService]
loadWindowWithCompletionBlock:
^(SessionWindow *window) {
if (window) {
[self windowDidLoad:window];
} else {
[self errorLoadingWindow];
}
}];
// Large blocks can be declared out-of-line.
void (^largeBlock)(void) = ^{
// ...
};
[operationQueue_ addOperationWithBlock:largeBlock];
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="Naming">
@ -743,8 +835,9 @@ Revision 2.24
<STYLEPOINT title="File Comments">
<SUMMARY>
Start each file with a copyright notice, followed by a
description of the contents of the file.
Start each file with a basic description of the contents of the file,
followed by an author, and then followed by a copyright notice and/or
license boilerplate.
</SUMMARY>
<BODY>
<SUBSECTION title="Legal Notice and Author Line">
@ -753,10 +846,12 @@ Revision 2.24
<p>
Every file should contain the following items, in order:
<ul>
<li>a basic description of the contents of the file</li>
<li>an author line</li>
<li>a copyright statement (for example,
<code>Copyright 2008 Google Inc.</code>)</li>
<li>a license boilerplate. Choose the appropriate boilerplate
for the license used by the project (for example,
<li>license boilerplate if neccessary. Choose the appropriate
boilerplate for the license used by the project (e.g.
Apache 2.0, BSD, LGPL, GPL)</li>
</ul>
</p>
@ -838,42 +933,46 @@ Revision 2.24
</SUMMARY>
<BODY>
<p>
Instance variable pointers to objects derived from NSObject are
presumed to be retained, and should be documented as <b>weak</b> if
they are not retained by the class. However, instance variables which
are labeled as IBOutlets are presumed to not be retained by the class,
and should be documented as <b>strong</b> if the class does retain
them.
Instance variables which are pointers to objects derived from NSObject
are presumed to be retained, and should be either commented as weak or
declared with the <b>__weak</b> lifetime qualifier when applicable.
Similarly, declared properties must specify a <b>weak</b> or
<b>assign</b> property attribute if they are not retained by the
class. An exception is instance variables labeled as IBOutlets in Mac
software, which are presumed to not be retained.
</p>
<p>
Where instance variables are pointers to CoreFoundation, C++, and
other non-Objective-C objects, they should always be documented in
comments as strong or weak. Be mindful that support for automatic C++
objects encapsulated in Objective-C objects is disabled by default, as
described <a href="http://chanson.livejournal.com/154253.html">here</a>.
other non-Objective-C objects, they should always be declared with
the __strong and __weak type modifiers to indicate which pointers are
and are not retained. CoreFoundation and other non-Objective-C object
pointers require explicit memory management, even when building for
automatic reference counting or garbage collection. When the __weak
type modifier is not allowed (e.g. C++ member variables when compiled
under clang), a comment should be used instead.
</p>
<p>
Examples of strong and weak documentation:
Be mindful that support for automatic C++ objects encapsulated in
Objective-C objects is disabled by default, as described <a href="http://chanson.livejournal.com/154253.html">here</a>.
</p>
<p>
Examples of strong and weak declarations:
<CODE_SNIPPET>
@interface MyDelegate : NSObject {
@private
IBOutlet NSButton* okButton_; // normal NSControl
IBOutlet NSMenu* myContextMenu_; // manually-loaded menu (strong)
IBOutlet NSButton *okButton_; // normal NSControl; implicitly weak on Mac only
AnObjcObject* doohickey_; // my doohickey
MyController* controller_; // so we can send msgs back (weak, owns me)
__weak MyObjcParent *parent_; // so we can send msgs back (owns me)
// non-NSObject pointers...
CWackyCPPClass* wacky_; // some cross-platform object (strong)
CFDictionaryRef* dict_; // (strong)
__strong CWackyCPPClass *wacky_; // some cross-platform object
__strong CFDictionaryRef *dict_;
}
@property(strong, nonatomic) NSString *doohickey;
@property(weak, nonatomic) NSString *parent;
@end
</CODE_SNIPPET>
<dl>
<dt>strong</dt><dd>The object will be <code>retain</code>'d by this class</dd>
<dt>weak</dt><dd>The object will be <b>not</b> be <code>retain</code>'d by this class
(e.g. a delegate).</dd>
</dl>
</p>
</BODY>
</STYLEPOINT>
@ -1171,7 +1270,52 @@ Revision 2.24
</BODY>
</STYLEPOINT>
<STYLEPOINT title="dealloc should process instance variables in declaration order">
<STYLEPOINT title="Avoid Accessors During init and dealloc">
<SUMMARY>
Instance subclasses may be in an inconsistent state during
<code>init</code> and <code>dealloc</code> method execution, so code in
those methods should avoid invoking accessors.
</SUMMARY>
<BODY>
<p>
Subclasses have not yet been initialized or have already deallocated
when <code>init</code> and <code>dealloc</code> methods execute, making
accessor methods potentially unreliable. Whenever practical, directly
assign to and release ivars in those methods rather than rely on
accessors.
</p>
<CODE_SNIPPET>
- (id)init {
self = [super init];
if (self) {
bar_ = [[NSMutableString alloc] init]; // good
}
return self;
}
- (void)dealloc {
[bar_ release]; // good
[super dealloc];
}
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
- (id)init {
self = [super init];
if (self) {
self.bar = [NSMutableString string]; // avoid
}
return self;
}
- (void)dealloc {
self.bar = nil; // avoid
[super dealloc];
}
</BAD_CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Dealloc Instance Variables in Declaration Order">
<SUMMARY>
<code>dealloc</code> should process instance variables in the same order
the <code>@interface</code> declares them, so it is easier for a reviewer
@ -1452,60 +1596,6 @@ Revision 2.24
<code>retain</code>.
</p>
</SUBSECTION>
<SUBSECTION title="Never synthesize CFType properties">
<p>
CFTypes should always have the <code>@dynamic</code> implementation
directive.
</p>
<p>
Since CFTypes can't have the <code>retain</code> property
attribute, the developer must handle retaining and releasing the
value themselves. In the rare case that you do actually want
assignment it is better to make that completely clear by actually
implementing the setter and getter and commenting why that is the
case.
</p>
</SUBSECTION>
<SUBSECTION title="List out all implementation directives">
<p>
Use implementation directives for all properties even if they are
<code>@dynamic</code> by default.
</p>
<p>
Even though <code>@dynamic</code> is default, explicitly list it out
with all of the other property implementation directives making it
clear how every property in a class is handled at a single glance.
</p>
<BAD_CODE_SNIPPET>
@interface MyClass : NSObject
@property(readonly) NSString *name;
@end
@implementation MyClass
.
.
.
- (NSString*)name {
return @"foo";
}
@end
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
@interface MyClass : NSObject
@property(readonly) NSString *name;
@end
@implementation MyClass
@dynamic name;
.
.
.
- (NSString*)name {
return @"foo";
}
@end
</CODE_SNIPPET>
</SUBSECTION>
<SUBSECTION title="Atomicity">
<p>
Be aware of the overhead of properties. By default, all synthesized
@ -1533,6 +1623,61 @@ Revision 2.24
</SUBSECTION>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Interfaces Without Instance Variables">
<SUMMARY>
Omit the empty set of braces on interfaces that do not declare any
instance variables.
</SUMMARY>
<BODY>
<CODE_SNIPPET>
@interface MyClass : NSObject
// Does a lot of stuff
- (void)fooBarBam;
@end
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
@interface MyClass : NSObject {
}
// Does a lot of stuff
- (void)fooBarBam;
@end
</BAD_CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Automatically Synthesized Instance Variables">
<SUMMARY>
<p>
For code that will run on iOS only, use of automatically synthesized
instance variables is preferred.
</p>
<p>
When synthesizing the instance variable, use
<code>@synthesize var = var_;</code> as this prevents accidentally calling
<code>var = blah;</code> when <code>self.var = blah;</code> is intended.
</p>
</SUMMARY>
<BODY>
<CODE_SNIPPET>
// Header file
@interface Foo : NSObject
// A guy walks into a bar.
@property(nonatomic, copy) NSString *bar;
@end
// Implementation file
@interface Foo ()
@property(nonatomic, retain) NSArray *baz;
@end
@implementation Foo
@synthesize bar = bar_;
@synthesize baz = baz_;
@end
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
@ -1601,7 +1746,7 @@ Revision 2.24
<HR/>
<p align="right">
Revision 2.24
Revision 2.36
</p>

357
pyguide.html
View File

@ -6,28 +6,33 @@
<LINK HREF="styleguide.css" type="text/css" rel="stylesheet">
<SCRIPT language="javascript" type="text/javascript">
function ShowHideByName(bodyName, buttonName) {
var bodyElements;
var linkElement;
function GetElementsByName(name) {
// Workaround a bug on old versions of opera.
if (document.getElementsByName) {
bodyElements = document.getElementsByName(bodyName);
linkElement = document.getElementsByName('link-' + buttonName)[0];
return document.getElementsByName(name);
} else {
bodyElements = [document.getElementById(bodyName)];
linkElement = document.getElementById('link-' + buttonName);
return [document.getElementById(name)];
}
}
/**
* @param {string} namePrefix The prefix of the body name.
* @param {function(boolean): boolean} getVisibility Computes the new
* visibility state, given the current one.
*/
function ChangeVisibility(namePrefix, getVisibility) {
var bodyName = namePrefix + '__body';
var buttonName = namePrefix + '__button';
var bodyElements = GetElementsByName(bodyName);
var linkElement = GetElementsByName('link-' + buttonName)[0];
if (bodyElements.length != 1) {
alert("ShowHideByName() got the wrong number of bodyElements: " + bodyElements.length);
throw Error('ShowHideByName() got the wrong number of bodyElements: ' +
bodyElements.length);
} else {
var bodyElement = bodyElements[0];
var buttonElement;
if (document.getElementsByName) {
var buttonElements = document.getElementsByName(buttonName);
buttonElement = buttonElements[0];
} else {
buttonElement = document.getElementById(buttonName);
}
if (bodyElement.style.display == "none" || bodyElement.style.display == "") {
var buttonElement = GetElementsByName(buttonName)[0];
var isVisible = bodyElement.style.display != "none";
if (getVisibility(isVisible)) {
bodyElement.style.display = "inline";
linkElement.style.display = "block";
buttonElement.innerHTML = '▽';
@ -39,14 +44,16 @@
}
}
function ShowHideByName(namePrefix) {
ChangeVisibility(namePrefix, function(old) { return !old; });
}
function ShowByName(namePrefix) {
ChangeVisibility(namePrefix, function() { return true; });
}
function ShowHideAll() {
var allButton;
if (document.getElementsByName) {
var allButtons = document.getElementsByName("show_hide_all_button");
allButton = allButtons[0];
} else {
allButton = document.getElementById("show_hide_all_button");
}
var allButton = GetElementsByName("show_hide_all_button")[0];
if (allButton.innerHTML == '▽') {
allButton.innerHTML = '▶';
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '▶');
@ -72,27 +79,56 @@
}
function EndsWith(str, suffix) {
var l = str.length - suffix.length;
return l >= 0 && str.indexOf(suffix, l) == l;
}
function RefreshVisibilityFromHashParam() {
var hashRegexp = new RegExp('#([^&#]*)$');
var hashMatch = hashRegexp.exec(window.location.href);
var anchor = hashMatch && GetElementsByName(hashMatch[1])[0];
var node = anchor;
var suffix = '__body';
while (node) {
var id = node.id;
var matched = id && EndsWith(id, suffix);
if (matched) {
var len = id.length - suffix.length;
ShowByName(matched.substring(0, len));
if (anchor.scrollIntoView) {
anchor.scrollIntoView();
}
return;
}
node = node.parentNode;
}
}
window.onhashchange = RefreshVisibilityFromHashParam;
window.onload = function() {
// if the URL contains "?showall=y", expand the details of all children
{
var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)");
var showHideAllValue = showHideAllRegex.exec(window.location.href);
if (showHideAllValue != null) {
if (showHideAllValue[2] == "y") {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '▽');
} else {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '▶');
}
var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)");
var showHideAllValue = showHideAllRegex.exec(window.location.href);
if (showHideAllValue != null) {
if (showHideAllValue[2] == "y") {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
"inline", '▽');
} else {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
"none", '▶');
}
var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
var showOneValue = showOneRegex.exec(window.location.href);
if (showOneValue != null) {
var body_name = showOneValue[2] + '__body';
var button_name = showOneValue[2] + '__button';
ShowHideByName(body_name, button_name);
}
}
var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
var showOneValue = showOneRegex.exec(window.location.href);
if (showOneValue) {
ShowHideByName(showOneValue[2]);
}
RefreshVisibilityFromHashParam();
}
</SCRIPT>
</HEAD>
@ -100,7 +136,7 @@
<H1>Google Python Style Guide</H1>
<p align="right">
Revision 2.20
Revision 2.28
</p>
<address>
@ -144,7 +180,7 @@
<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="link_button" id="link-Displaying_Hidden_Details_in_this_Guide__button" name="link-Displaying_Hidden_Details_in_this_Guide__button"><A href="?showone=Displaying_Hidden_Details_in_this_Guide#Displaying_Hidden_Details_in_this_Guide">
link
</A></SPAN><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>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Displaying_Hidden_Details_in_this_Guide')" name="Displaying_Hidden_Details_in_this_Guide__button" id="Displaying_Hidden_Details_in_this_Guide__button">▶</SPAN>
<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
@ -183,7 +219,7 @@
<H3><A name="pychecker" id="pychecker">pychecker</A></H3>
<SPAN class="link_button" id="link-pychecker__button" name="link-pychecker__button"><A href="?showone=pychecker#pychecker">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('pychecker__body','pychecker__button')" name="pychecker__button" id="pychecker__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('pychecker')" name="pychecker__button" id="pychecker__button">▶</SPAN>
<DIV style="display:inline;" class="">
Run <code>pychecker</code> over your code.
</DIV>
@ -255,7 +291,7 @@
<H3><A name="Imports" id="Imports">Imports</A></H3>
<SPAN class="link_button" id="link-Imports__button" name="link-Imports__button"><A href="?showone=Imports#Imports">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports__body','Imports__button')" name="Imports__button" id="Imports__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports')" name="Imports__button" id="Imports__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use <code>import</code>s for packages and modules only.
</DIV>
@ -283,7 +319,7 @@
prefix.
<br>
Use <code>from x import y as z</code> if two modules named
<code>z</code> are to be imported or if <code>y</code> is an
<code>y</code> are to be imported or if <code>y</code> is an
inconveniently long name.
</P>
For example the module
@ -305,7 +341,7 @@
<H3><A name="Packages" id="Packages">Packages</A></H3>
<SPAN class="link_button" id="link-Packages__button" name="link-Packages__button"><A href="?showone=Packages#Packages">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Packages__body','Packages__button')" name="Packages__button" id="Packages__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Packages')" name="Packages__button" id="Packages__button">▶</SPAN>
<DIV style="display:inline;" class="">
Import each module using the full pathname location of the module.
</DIV>
@ -340,7 +376,7 @@ from sound.effects import echo
<H3><A name="Exceptions" id="Exceptions">Exceptions</A></H3>
<SPAN class="link_button" id="link-Exceptions__button" name="link-Exceptions__button"><A href="?showone=Exceptions#Exceptions">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Exceptions__body','Exceptions__button')" name="Exceptions__button" id="Exceptions__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Exceptions')" name="Exceptions__button" id="Exceptions__button">▶</SPAN>
<DIV style="display:inline;" class="">
Exceptions are allowed but must be used carefully.
</DIV>
@ -408,7 +444,7 @@ from sound.effects import echo
<H3><A name="Global_variables" id="Global_variables">Global variables</A></H3>
<SPAN class="link_button" id="link-Global_variables__button" name="link-Global_variables__button"><A href="?showone=Global_variables#Global_variables">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Global_variables__body','Global_variables__button')" name="Global_variables__button" id="Global_variables__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Global_variables')" name="Global_variables__button" id="Global_variables__button">▶</SPAN>
<DIV style="display:inline;" class="">
Avoid global variables.
</DIV>
@ -449,7 +485,7 @@ from sound.effects import echo
<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="link_button" id="link-Nested/Local/Inner_Classes_and_Functions__button" name="link-Nested/Local/Inner_Classes_and_Functions__button"><A href="?showone=Nested/Local/Inner_Classes_and_Functions#Nested/Local/Inner_Classes_and_Functions">
link
</A></SPAN><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>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Nested/Local/Inner_Classes_and_Functions')" name="Nested/Local/Inner_Classes_and_Functions__button" id="Nested/Local/Inner_Classes_and_Functions__button">▶</SPAN>
<DIV style="display:inline;" class="">
Nested/local/inner classes and functions are fine.
</DIV>
@ -479,7 +515,7 @@ from sound.effects import echo
<H3><A name="List_Comprehensions" id="List_Comprehensions">List Comprehensions</A></H3>
<SPAN class="link_button" id="link-List_Comprehensions__button" name="link-List_Comprehensions__button"><A href="?showone=List_Comprehensions#List_Comprehensions">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('List_Comprehensions__body','List_Comprehensions__button')" name="List_Comprehensions__button" id="List_Comprehensions__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('List_Comprehensions')" name="List_Comprehensions__button" id="List_Comprehensions__button">▶</SPAN>
<DIV style="display:inline;" class="">
Okay to use for simple cases.
</DIV>
@ -548,7 +584,7 @@ from sound.effects import echo
<H3><A name="Default_Iterators_and_Operators" id="Default_Iterators_and_Operators">Default Iterators and Operators</A></H3>
<SPAN class="link_button" id="link-Default_Iterators_and_Operators__button" name="link-Default_Iterators_and_Operators__button"><A href="?showone=Default_Iterators_and_Operators#Default_Iterators_and_Operators">
link
</A></SPAN><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>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Iterators_and_Operators')" name="Default_Iterators_and_Operators__button" id="Default_Iterators_and_Operators__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use default iterators and operators for types that support them,
like lists, dictionaries, and files.
@ -593,7 +629,7 @@ from sound.effects import echo
<H3><A name="Generators" id="Generators">Generators</A></H3>
<SPAN class="link_button" id="link-Generators__button" name="link-Generators__button"><A href="?showone=Generators#Generators">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Generators__body','Generators__button')" name="Generators__button" id="Generators__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Generators')" name="Generators__button" id="Generators__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use generators as needed.
</DIV>
@ -626,7 +662,7 @@ from sound.effects import echo
<H3><A name="Lambda_Functions" id="Lambda_Functions">Lambda Functions</A></H3>
<SPAN class="link_button" id="link-Lambda_Functions__button" name="link-Lambda_Functions__button"><A href="?showone=Lambda_Functions#Lambda_Functions">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lambda_Functions__body','Lambda_Functions__button')" name="Lambda_Functions__button" id="Lambda_Functions__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lambda_Functions')" name="Lambda_Functions__button" id="Lambda_Functions__button">▶</SPAN>
<DIV style="display:inline;" class="">
Okay for one-liners.
</DIV>
@ -666,7 +702,7 @@ from sound.effects import echo
<H3><A name="Default_Argument_Values" id="Default_Argument_Values">Default Argument Values</A></H3>
<SPAN class="link_button" id="link-Default_Argument_Values__button" name="link-Default_Argument_Values__button"><A href="?showone=Default_Argument_Values#Default_Argument_Values">
link
</A></SPAN><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>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Argument_Values')" name="Default_Argument_Values__button" id="Default_Argument_Values__button">▶</SPAN>
<DIV style="display:inline;" class="">
Okay in most cases.
</DIV>
@ -727,7 +763,7 @@ from sound.effects import echo
<H3><A name="Properties" id="Properties">Properties</A></H3>
<SPAN class="link_button" id="link-Properties__button" name="link-Properties__button"><A href="?showone=Properties#Properties">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Properties__body','Properties__button')" name="Properties__button" id="Properties__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Properties')" name="Properties__button" id="Properties__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use properties for accessing or setting data where you would
normally have used simple, lightweight accessor or setter methods.
@ -823,7 +859,7 @@ from sound.effects import echo
<H3><A name="True/False_evaluations" id="True/False_evaluations">True/False evaluations</A></H3>
<SPAN class="link_button" id="link-True/False_evaluations__button" name="link-True/False_evaluations__button"><A href="?showone=True/False_evaluations#True/False_evaluations">
link
</A></SPAN><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>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('True/False_evaluations')" name="True/False_evaluations__button" id="True/False_evaluations__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use the "implicit" false if at all possible.
</DIV>
@ -908,7 +944,7 @@ from sound.effects import echo
<H3><A name="Deprecated_Language_Features" id="Deprecated_Language_Features">Deprecated Language Features</A></H3>
<SPAN class="link_button" id="link-Deprecated_Language_Features__button" name="link-Deprecated_Language_Features__button"><A href="?showone=Deprecated_Language_Features#Deprecated_Language_Features">
link
</A></SPAN><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>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Deprecated_Language_Features')" name="Deprecated_Language_Features__button" id="Deprecated_Language_Features__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use string methods instead of the <code>string</code> module
where possible. Use function call syntax instead
@ -944,7 +980,7 @@ from sound.effects import echo
<H3><A name="Lexical_Scoping" id="Lexical_Scoping">Lexical Scoping</A></H3>
<SPAN class="link_button" id="link-Lexical_Scoping__button" name="link-Lexical_Scoping__button"><A href="?showone=Lexical_Scoping#Lexical_Scoping">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lexical_Scoping__body','Lexical_Scoping__button')" name="Lexical_Scoping__button" id="Lexical_Scoping__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lexical_Scoping')" name="Lexical_Scoping__button" id="Lexical_Scoping__button">▶</SPAN>
<DIV style="display:inline;" class="">
Okay to use.
</DIV>
@ -1010,7 +1046,7 @@ from sound.effects import echo
<H3><A name="Function_and_Method_Decorators" id="Function_and_Method_Decorators">Function and Method Decorators</A></H3>
<SPAN class="link_button" id="link-Function_and_Method_Decorators__button" name="link-Function_and_Method_Decorators__button"><A href="?showone=Function_and_Method_Decorators#Function_and_Method_Decorators">
link
</A></SPAN><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>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Function_and_Method_Decorators')" name="Function_and_Method_Decorators__button" id="Function_and_Method_Decorators__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use decorators judiciously when there is a clear advantage.
</DIV>
@ -1080,7 +1116,7 @@ from sound.effects import echo
<H3><A name="Threading" id="Threading">Threading</A></H3>
<SPAN class="link_button" id="link-Threading__button" name="link-Threading__button"><A href="?showone=Threading#Threading">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Threading__body','Threading__button')" name="Threading__button" id="Threading__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Threading')" name="Threading__button" id="Threading__button">▶</SPAN>
<DIV style="display:inline;" class="">
Do not rely on the atomicity of built-in types.
</DIV>
@ -1110,7 +1146,7 @@ from sound.effects import echo
<H3><A name="Power_Features" id="Power_Features">Power Features</A></H3>
<SPAN class="link_button" id="link-Power_Features__button" name="link-Power_Features__button"><A href="?showone=Power_Features#Power_Features">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Power_Features__body','Power_Features__button')" name="Power_Features__button" id="Power_Features__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Power_Features')" name="Power_Features__button" id="Power_Features__button">▶</SPAN>
<DIV style="display:inline;" class="">
Avoid these features.
</DIV>
@ -1148,7 +1184,7 @@ from sound.effects import echo
<H3><A name="Semicolons" id="Semicolons">Semicolons</A></H3>
<SPAN class="link_button" id="link-Semicolons__button" name="link-Semicolons__button"><A href="?showone=Semicolons#Semicolons">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Semicolons__body','Semicolons__button')" name="Semicolons__button" id="Semicolons__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Semicolons')" name="Semicolons__button" id="Semicolons__button">▶</SPAN>
<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.
@ -1160,7 +1196,7 @@ from sound.effects import echo
<H3><A name="Line_length" id="Line_length">Line length</A></H3>
<SPAN class="link_button" id="link-Line_length__button" name="link-Line_length__button"><A href="?showone=Line_length#Line_length">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Line_length__body','Line_length__button')" name="Line_length__button" id="Line_length__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Line_length')" name="Line_length__button" id="Line_length__button">▶</SPAN>
<DIV style="display:inline;" class="">
Maximum line length is <em>80 characters</em>.
</DIV>
@ -1171,6 +1207,10 @@ from sound.effects import echo
earlier.
</p>
<p>
Do not use backslash line continuation.
</p>
<p>
Make use of Python's
@ -1209,7 +1249,7 @@ from sound.effects import echo
<H3><A name="Parentheses" id="Parentheses">Parentheses</A></H3>
<SPAN class="link_button" id="link-Parentheses__button" name="link-Parentheses__button"><A href="?showone=Parentheses#Parentheses">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Parentheses__body','Parentheses__button')" name="Parentheses__button" id="Parentheses__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Parentheses')" name="Parentheses__button" id="Parentheses__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use parentheses sparingly.
</DIV>
@ -1241,7 +1281,7 @@ from sound.effects import echo
<H3><A name="Indentation" id="Indentation">Indentation</A></H3>
<SPAN class="link_button" id="link-Indentation__button" name="link-Indentation__button"><A href="?showone=Indentation#Indentation">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Indentation__body','Indentation__button')" name="Indentation__button" id="Indentation__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Indentation')" name="Indentation__button" id="Indentation__button">▶</SPAN>
<DIV style="display:inline;" class="">
Indent your code blocks with <em>4 spaces</em>.
</DIV>
@ -1278,7 +1318,7 @@ from sound.effects import echo
<H3><A name="Blank_Lines" id="Blank_Lines">Blank Lines</A></H3>
<SPAN class="link_button" id="link-Blank_Lines__button" name="link-Blank_Lines__button"><A href="?showone=Blank_Lines#Blank_Lines">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Blank_Lines__body','Blank_Lines__button')" name="Blank_Lines__button" id="Blank_Lines__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Blank_Lines')" name="Blank_Lines__button" id="Blank_Lines__button">▶</SPAN>
<DIV style="display:inline;" class="">
Two blank lines between top-level definitions, one blank line
between method definitions.
@ -1297,7 +1337,7 @@ from sound.effects import echo
<H3><A name="Whitespace" id="Whitespace">Whitespace</A></H3>
<SPAN class="link_button" id="link-Whitespace__button" name="link-Whitespace__button"><A href="?showone=Whitespace#Whitespace">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Whitespace__body','Whitespace__button')" name="Whitespace__button" id="Whitespace__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Whitespace')" name="Whitespace__button" id="Whitespace__button">▶</SPAN>
<DIV style="display:inline;" class="">
Follow standard typographic rules for the use of spaces around
punctuation.
@ -1376,24 +1416,18 @@ from sound.effects import echo
<H3><A name="Shebang_Line" id="Shebang_Line">Shebang Line</A></H3>
<SPAN class="link_button" id="link-Shebang_Line__button" name="link-Shebang_Line__button"><A href="?showone=Shebang_Line#Shebang_Line">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Shebang_Line__body','Shebang_Line__button')" name="Shebang_Line__button" id="Shebang_Line__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Shebang_Line')" name="Shebang_Line__button" id="Shebang_Line__button">▶</SPAN>
<DIV style="display:inline;" class="">
All <code>.py</code> files (except <code>__init__.py</code> package
files) should begin with a
<code>#!/usr/bin/python&lt;version&gt;</code>
shebang line.
Most <code>.py</code> files do not need to start with a
<code>#!</code> line. Start the main file of a binary with
<code>#!/usr/bin/python</code>.
</DIV>
<DIV class=""><DIV class="stylepoint_body" name="Shebang_Line__body" id="Shebang_Line__body" style="display: none">
<p>
Always use the most specific version that you can to ensure
compatibility. For examples, if your program uses a language feature
that that first appeared in Python 2.4, use
<code>/usr/bin/python2.4</code> (or something newer) instead of
<code>/usr/bin/python2</code>. Otherwise, your program might not
behave the way you expect it to, because the interpreter uses an
older version of the language.
This line is used by the kernel to find the Python interpreter, but is
ignored by Python when importing modules. It is only necessary on a
file that will be executed directly.
</p>
</DIV></DIV>
</DIV>
@ -1402,7 +1436,7 @@ from sound.effects import echo
<H3><A name="Comments" id="Comments">Comments</A></H3>
<SPAN class="link_button" id="link-Comments__button" name="link-Comments__button"><A href="?showone=Comments#Comments">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Comments__body','Comments__button')" name="Comments__button" id="Comments__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Comments')" name="Comments__button" id="Comments__button">▶</SPAN>
<DIV style="display:inline;" class="">
Be sure to use the right style for module, function, method and in-line
comments.
@ -1450,24 +1484,66 @@ from sound.effects import echo
<SPAN class="stylepoint_subsection">Functions and Methods</SPAN>
<p>
Any function or method which is not both obvious and very short
needs a doc string. Additionally, any externally accessible
function or method regardless of length or simplicity needs a
doc string. The doc string should include what the function does
and have detailed descriptions of the input and output. It
should not, generally, describe how it does it unless it's some
complicated algorithm. For tricky code block/inline comments
within the code are more appropriate. The doc string should give
enough information to write a call to the function without
looking at a single line of the function's code. Args should be
individually documented, an explanation following after a colon,
and should use a uniform hanging indent of 2 or 4 spaces. The
doc string should specify the expected types where specific types
are required. A "Raises:" section should list all exceptions
that can be raised by the function. The doc string for generator
functions should use "Yields:" rather than "Returns:".
As used in this section "function" applies to methods, function, and
generators.
</p>
<p>
A function must have a docstring, unless it meets all of the following
criteria:
<ul>
<li>not externally visible</li>
<li>very short</li>
<li>obvious</li>
</ul>
</p>
<p>
A docstring should give enough information to write a call to the function
without reading the function's code. A docstring should describe the
function's calling syntax and its semantics, not its implementation. For
tricky code, comments alongside the code are more appropriate than using
docstrings.
</p>
<p>
Certain aspects of a function should be documented in special sections,
listed below. Each section begins with a heading line, which ends with a
colon. Sections should be indented two spaces, except for the heading.
</p>
<dl>
<dt>Args:</dt>
<dd>
List each parameter by name. A description should follow the name, and
be separated by a colon and a space. If the description is too long to
fit on a single 80-character line, use a hanging indent of 2 or 4 spaces
(be consistent with the rest of the file).
<p>
The description should mention required type(s) and the meaning of
the argument.
</p>
<p>
If a function accepts *foo (variable length argument lists) and/or
**bar (arbitrary keyword arguments), they should be listed as *foo and
**bar.
</p>
</dd>
<dt>Returns: (or Yields: for generators)</dt>
<dd>
Describe the type and semantics of the return value. If the function
only returns None, this section is not required.
</dd>
<dt>Raises:</dt>
<dd>
List all exceptions that are relevant to the interface.
</dd>
</dl>
<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.
@ -1581,7 +1657,7 @@ from sound.effects import echo
<H3><A name="Classes" id="Classes">Classes</A></H3>
<SPAN class="link_button" id="link-Classes__button" name="link-Classes__button"><A href="?showone=Classes#Classes">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Classes__body','Classes__button')" name="Classes__button" id="Classes__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Classes')" name="Classes__button" id="Classes__button">▶</SPAN>
<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.
@ -1627,7 +1703,7 @@ from sound.effects import echo
<H3><A name="Strings" id="Strings">Strings</A></H3>
<SPAN class="link_button" id="link-Strings__button" name="link-Strings__button"><A href="?showone=Strings#Strings">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Strings__body','Strings__button')" name="Strings__button" id="Strings__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Strings')" name="Strings__button" id="Strings__button">▶</SPAN>
<DIV style="display:inline;" class="">
Use the <code>%</code> operator for formatting strings,
even when the parameters are all strings. Use your best judgement
@ -1681,40 +1757,47 @@ Don'<span class="external"></span>t do this.
<H3><A name="TODO_Comments" id="TODO_Comments">TODO Comments</A></H3>
<SPAN class="link_button" id="link-TODO_Comments__button" name="link-TODO_Comments__button"><A href="?showone=TODO_Comments#TODO_Comments">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('TODO_Comments__body','TODO_Comments__button')" name="TODO_Comments__button" id="TODO_Comments__button">▶</SPAN>
<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.
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('TODO_Comments')" name="TODO_Comments__button" id="TODO_Comments__button">▶</SPAN>
<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.
</DIV>
<DIV class=""><DIV class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none">
<p>
<code>TODO</code>s should include the string <code>TODO</code> in
all caps, followed by the
name, e-mail address, or other
identifier
of the person who can best provide context about the problem
referenced by the <code>TODO</code>,
in parentheses. A colon is optional. A comment explaining what there
is to do is required. The main purpose is to have
a consistent <code>TODO</code> format that can be searched to find the
person who can provide more details upon request. A
<code>TODO</code> is not a commitment that the person referenced
will fix the problem. Thus when you create a <code>TODO</code>, it is
almost always your
name
that is given.
</p>
<DIV class=""><PRE># TODO(kl@gmail.com): Use a "*" here for string repetition.
# 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>
</DIV></DIV>
</DIV>
<DIV class=""><DIV class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none">
<p>
<code>TODO</code>s should include the string <code>TODO</code> in
all caps, followed by your
name, e-mail address, or other
identifier
in parentheses. A colon is optional. A comment explaining what there
is to do is required. The main purpose is to have
a consistent <code>TODO</code> format searchable by the person
adding the comment (who can provide more details upon request). A
<code>TODO</code> is not a commitment to provide the fix yourself.
</p>
<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>
</DIV></DIV>
</DIV>
<DIV class="">
<H3><A name="Imports_formatting" id="Imports_formatting">Imports formatting</A></H3>
<SPAN class="link_button" id="link-Imports_formatting__button" name="link-Imports_formatting__button"><A href="?showone=Imports_formatting#Imports_formatting">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports_formatting__body','Imports_formatting__button')" name="Imports_formatting__button" id="Imports_formatting__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports_formatting')" name="Imports_formatting__button" id="Imports_formatting__button">▶</SPAN>
<DIV style="display:inline;" class="">
Imports should be on separate lines.
</DIV>
@ -1757,7 +1840,7 @@ Don'<span class="external"></span>t do this.
<H3><A name="Statements" id="Statements">Statements</A></H3>
<SPAN class="link_button" id="link-Statements__button" name="link-Statements__button"><A href="?showone=Statements#Statements">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Statements__body','Statements__button')" name="Statements__button" id="Statements__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Statements')" name="Statements__button" id="Statements__button">▶</SPAN>
<DIV style="display:inline;" class="">
Generally only one statement per line.
</DIV>
@ -1794,7 +1877,7 @@ Don'<span class="external"></span>t do this.
<H3><A name="Access_Control" id="Access_Control">Access Control</A></H3>
<SPAN class="link_button" id="link-Access_Control__button" name="link-Access_Control__button"><A href="?showone=Access_Control#Access_Control">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Access_Control__body','Access_Control__button')" name="Access_Control__button" id="Access_Control__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Access_Control')" name="Access_Control__button" id="Access_Control__button">▶</SPAN>
<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
@ -1817,11 +1900,13 @@ Don'<span class="external"></span>t do this.
<H3><A name="Naming" id="Naming">Naming</A></H3>
<SPAN class="link_button" id="link-Naming__button" name="link-Naming__button"><A href="?showone=Naming#Naming">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Naming__body','Naming__button')" name="Naming__button" id="Naming__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Naming')" name="Naming__button" id="Naming__button">▶</SPAN>
<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>
<code>module_name, package_name, ClassName,
method_name, ExceptionName,
function_name, GLOBAL_CONSTANT_NAME,
global_var_name, instance_var_name, function_parameter_name,
local_var_name.</code>
</DIV>
<DIV class=""><DIV class="stylepoint_body" name="Naming__body" id="Naming__body" style="display: none">
<P class="">
@ -1958,7 +2043,7 @@ Don'<span class="external"></span>t do this.
<H3><A name="Main" id="Main">Main</A></H3>
<SPAN class="link_button" id="link-Main__button" name="link-Main__button"><A href="?showone=Main#Main">
link
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Main__body','Main__button')" name="Main__button" id="Main__button">▶</SPAN>
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Main')" name="Main__button" id="Main__button">▶</SPAN>
<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
@ -2027,7 +2112,7 @@ Don'<span class="external"></span>t do this.
<p align="right">
Revision 2.20
Revision 2.28
</p>

120
styleguide.xsl
View File

@ -30,28 +30,33 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
<SCRIPT language="javascript" type="text/javascript">
function ShowHideByName(bodyName, buttonName) {
var bodyElements;
var linkElement;
function GetElementsByName(name) {
// Workaround a bug on old versions of opera.
if (document.getElementsByName) {
bodyElements = document.getElementsByName(bodyName);
linkElement = document.getElementsByName('link-' + buttonName)[0];
return document.getElementsByName(name);
} else {
bodyElements = [document.getElementById(bodyName)];
linkElement = document.getElementById('link-' + buttonName);
return [document.getElementById(name)];
}
}
/**
* @param {string} namePrefix The prefix of the body name.
* @param {function(boolean): boolean} getVisibility Computes the new
* visibility state, given the current one.
*/
function ChangeVisibility(namePrefix, getVisibility) {
var bodyName = namePrefix + '<xsl:value-of select="$body_suffix"/>';
var buttonName = namePrefix + '<xsl:value-of select="$button_suffix"/>';
var bodyElements = GetElementsByName(bodyName);
var linkElement = GetElementsByName('link-' + buttonName)[0];
if (bodyElements.length != 1) {
alert("ShowHideByName() got the wrong number of bodyElements: " + bodyElements.length);
throw Error('ShowHideByName() got the wrong number of bodyElements: ' +
bodyElements.length);
} else {
var bodyElement = bodyElements[0];
var buttonElement;
if (document.getElementsByName) {
var buttonElements = document.getElementsByName(buttonName);
buttonElement = buttonElements[0];
} else {
buttonElement = document.getElementById(buttonName);
}
if (bodyElement.style.display == "none" || bodyElement.style.display == "") {
var buttonElement = GetElementsByName(buttonName)[0];
var isVisible = bodyElement.style.display != "none";
if (getVisibility(isVisible)) {
bodyElement.style.display = "inline";
linkElement.style.display = "block";
buttonElement.innerHTML = '<xsl:value-of select="$hide_button_text"/>';
@ -63,14 +68,16 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
}
}
function ShowHideByName(namePrefix) {
ChangeVisibility(namePrefix, function(old) { return !old; });
}
function ShowByName(namePrefix) {
ChangeVisibility(namePrefix, function() { return true; });
}
function ShowHideAll() {
var allButton;
if (document.getElementsByName) {
var allButtons = document.getElementsByName("show_hide_all_button");
allButton = allButtons[0];
} else {
allButton = document.getElementById("show_hide_all_button");
}
var allButton = GetElementsByName("show_hide_all_button")[0];
if (allButton.innerHTML == '<xsl:value-of select="$hide_button_text"/>') {
allButton.innerHTML = '<xsl:value-of select="$show_button_text"/>';
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>');
@ -96,27 +103,56 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
}
function EndsWith(str, suffix) {
var l = str.length - suffix.length;
return l >= 0 &amp;&amp; str.indexOf(suffix, l) == l;
}
function RefreshVisibilityFromHashParam() {
var hashRegexp = new RegExp('#([^&amp;#]*)$');
var hashMatch = hashRegexp.exec(window.location.href);
var anchor = hashMatch &amp;&amp; GetElementsByName(hashMatch[1])[0];
var node = anchor;
var suffix = '<xsl:value-of select="$body_suffix"/>';
while (node) {
var id = node.id;
var matched = id &amp;&amp; EndsWith(id, suffix);
if (matched) {
var len = id.length - suffix.length;
ShowByName(matched.substring(0, len));
if (anchor.scrollIntoView) {
anchor.scrollIntoView();
}
return;
}
node = node.parentNode;
}
}
window.onhashchange = RefreshVisibilityFromHashParam;
window.onload = function() {
// if the URL contains "?showall=y", expand the details of all children
{
var showHideAllRegex = new RegExp("[\\?&amp;](showall)=([^&amp;#]*)");
var showHideAllValue = showHideAllRegex.exec(window.location.href);
if (showHideAllValue != null) {
if (showHideAllValue[2] == "y") {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '<xsl:value-of select="$hide_button_text"/>');
} else {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>');
}
var showHideAllRegex = new RegExp("[\\?&amp;](showall)=([^&amp;#]*)");
var showHideAllValue = showHideAllRegex.exec(window.location.href);
if (showHideAllValue != null) {
if (showHideAllValue[2] == "y") {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
"inline", '<xsl:value-of select="$hide_button_text"/>');
} else {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
"none", '<xsl:value-of select="$show_button_text"/>');
}
var showOneRegex = new RegExp("[\\?&amp;](showone)=([^&amp;#]*)");
var showOneValue = showOneRegex.exec(window.location.href);
if (showOneValue != null) {
var body_name = showOneValue[2] + '<xsl:value-of select="$body_suffix"/>';
var button_name = showOneValue[2] + '<xsl:value-of select="$button_suffix"/>';
ShowHideByName(body_name, button_name);
}
}
var showOneRegex = new RegExp("[\\?&amp;](showone)=([^&amp;#]*)");
var showOneValue = showOneRegex.exec(window.location.href);
if (showOneValue) {
ShowHideByName(showOneValue[2]);
}
RefreshVisibilityFromHashParam();
}
</SCRIPT>
</HEAD>
@ -214,9 +250,7 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
</xsl:variable>
<xsl:variable name="onclick_definition">
<xsl:text>javascript:ShowHideByName('</xsl:text>
<xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$body_suffix"/>
<xsl:text>','</xsl:text>
<xsl:value-of select="$buttonName"/>
<xsl:value-of select="$stylepoint_name"/>
<xsl:text>')</xsl:text>
</xsl:variable>
<SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}">