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

1649
javascriptguide.xml
View File

File diff suppressed because it is too large Load Diff

435
objcguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 2.24 Revision 2.36
</p> </p>
@ -16,7 +16,7 @@ Revision 2.24
Dave MacLachlan Dave MacLachlan
</address> </address>
</div> </div>
<OVERVIEW> <OVERVIEW>
<CATEGORY title="Important Note"> <CATEGORY title="Important Note">
@ -102,7 +102,7 @@ Revision 2.24
Code meant to be shared across different projects is a good candidate to Code meant to be shared across different projects is a good candidate to
be included in this repository. be included in this repository.
</p> </p>
<p> <p>
@ -117,7 +117,7 @@ Revision 2.24
</OVERVIEW> </OVERVIEW>
<CATEGORY title="Example"> <CATEGORY title="Example">
<p> <p>
They say an example is worth a thousand words so let's start off with an They say an example is worth a thousand words so let's start off with an
example that should give you a feel for the style, spacing, naming, etc. example that should give you a feel for the style, spacing, naming, etc.
@ -129,110 +129,111 @@ Revision 2.24
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
// GTMFoo.h // Foo.h
// FooProject // AwesomeProject
// //
// Created by Greg Miller on 6/13/08. // Created by Greg Miller on 6/13/08.
// Copyright 2008 Google, Inc. All rights reserved. // Copyright 2008 Google, Inc. All rights reserved.
// //
#import &lt;Foundation/Foundation.h&gt; #import &lt;Foundation/Foundation.h&gt;
// A sample class demonstrating good Objective-C style. All interfaces, // A sample class demonstrating good Objective-C style. All interfaces,
// categories, and protocols (read: all top-level declarations in a header) // categories, and protocols (read: all top-level declarations in a header)
// MUST be commented. Comments must also be adjacent to the object they're // MUST be commented. Comments must also be adjacent to the object they're
// documenting. // documenting.
// //
// (no blank line between this comment and the interface) // (no blank line between this comment and the interface)
@interface GTMFoo : NSObject { @interface Foo : NSObject {
@private @private
NSString *foo_;
NSString *bar_; NSString *bar_;
NSString *bam_;
} }
// Returns an autoreleased instance of GMFoo. See -initWithString: for details // Returns an autoreleased instance of Foo. See -initWithBar: for details
// about the argument. // about |bar|.
+ (id)fooWithString:(NSString *)string; + (id)fooWithBar:(NSString *)bar;
// Designated initializer. |string| will be copied and assigned to |foo_|. // Designated initializer. |bar| is a thing that represents a thing that
- (id)initWithString:(NSString *)string; // does a thing.
- (id)initWithBar:(NSString *)bar;
// Gets and sets the string for |foo_|.
- (NSString *)foo; // Gets and sets |bar_|.
- (void)setFoo:(NSString *)newFoo; - (NSString *)bar;
- (void)setBar:(NSString *)bar;
// Does some work on |blah| and returns YES if the work was completed
// successfuly, and NO otherwise. // Does some work with |blah| and returns YES if the work was completed
- (BOOL)doWorkWithString:(NSString *)blah; // successfully, and NO otherwise.
- (BOOL)doWorkWithBlah:(NSString *)blah;
@end @end
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
An example source file, demonstrating the correct commenting and spacing An example source file, demonstrating the correct commenting and spacing
for the <code>@implementation</code> of an interface. It also includes the for the <code>@implementation</code> of an interface. It also includes the
reference implementations for important methods like getters and setters, reference implementations for important methods like getters and setters,
<code>init</code>, and <code>dealloc</code>. <code>init</code>, and <code>dealloc</code>.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
// //
// GTMFoo.m // Foo.m
// FooProject // AwesomeProject
// //
// Created by Greg Miller on 6/13/08. // Created by Greg Miller on 6/13/08.
// Copyright 2008 Google, Inc. All rights reserved. // Copyright 2008 Google, Inc. All rights reserved.
// //
#import "GTMFoo.h" #import "Foo.h"
@implementation GTMFoo @implementation Foo
+ (id)fooWithString:(NSString *)string { + (id)fooWithBar:(NSString *)bar {
return [[[self alloc] initWithString:string] autorelease]; return [[[self alloc] initWithBar:bar] autorelease];
} }
// Must always override super's designated initializer. // Must always override super's designated initializer.
- (id)init { - (id)init {
return [self initWithString:nil]; return [self initWithBar:nil];
} }
- (id)initWithString:(NSString *)string { - (id)initWithBar:(NSString *)bar {
if ((self = [super init])) { if ((self = [super init])) {
foo_ = [string copy]; bar_ = [bar copy];
bar_ = [[NSString alloc] initWithFormat:@"hi %d", 3]; bam_ = [[NSString alloc] initWithFormat:@"hi %d", 3];
} }
return self; return self;
} }
- (void)dealloc { - (void)dealloc {
[foo_ release];
[bar_ release]; [bar_ release];
[bam_ release];
[super dealloc]; [super dealloc];
} }
- (NSString *)foo { - (NSString *)bar {
return foo_; return bar_;
} }
- (void)setFoo:(NSString *)newFoo { - (void)setBar:(NSString *)bar {
[foo_ autorelease]; [bar_ autorelease];
foo_ = [newFoo copy]; bar_ = [bar copy];
} }
- (BOOL)doWorkWithString:(NSString *)blah { - (BOOL)doWorkWithBlah:(NSString *)blah {
// ... // ...
return NO; return NO;
} }
@end @end
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
Blank lines before and after <code>@interface</code>, Blank lines before and after <code>@interface</code>,
<code>@implementation</code>, and <code>@end</code> are optional. If your <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>). line should come after the closing brace (<code>}</code>).
<p> <p>
</p> </p>
@ -260,14 +261,19 @@ Revision 2.24
<STYLEPOINT title="Line Length"> <STYLEPOINT title="Line Length">
<SUMMARY> <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> </SUMMARY>
<BODY> <BODY>
<p> <p>
Even though Objective-C tends to be a more verbose language than C++, Strive to keep your code within 80 columns. We realize that Objective C
to aid in the interoperability with that guide, we have decided is a verbose language and in some cases it may be more readable to
to keep the limit at 80 columns as well. It's easier to live with extend slightly beyond 80 columns, but this should definitely be the
than you might expect. 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>
<p> <p>
@ -435,7 +441,7 @@ Revision 2.24
<BODY> <BODY>
<p> <p>
This applies to class declarations, instance variables, and method This applies to class declarations, instance variables, and method
delcarations. For example: declarations. For example:
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
@interface MyProtocoledClass : NSObject&lt;NSWindowDelegate&gt; { @interface MyProtocoledClass : NSObject&lt;NSWindowDelegate&gt; {
@ -448,6 +454,92 @@ Revision 2.24
</BODY> </BODY>
</STYLEPOINT> </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>
<CATEGORY title="Naming"> <CATEGORY title="Naming">
@ -743,8 +835,9 @@ Revision 2.24
<STYLEPOINT title="File Comments"> <STYLEPOINT title="File Comments">
<SUMMARY> <SUMMARY>
Start each file with a copyright notice, followed by a Start each file with a basic description of the contents of the file,
description of the contents of the file. followed by an author, and then followed by a copyright notice and/or
license boilerplate.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<SUBSECTION title="Legal Notice and Author Line"> <SUBSECTION title="Legal Notice and Author Line">
@ -753,10 +846,12 @@ Revision 2.24
<p> <p>
Every file should contain the following items, in order: Every file should contain the following items, in order:
<ul> <ul>
<li>a basic description of the contents of the file</li>
<li>an author line</li>
<li>a copyright statement (for example, <li>a copyright statement (for example,
<code>Copyright 2008 Google Inc.</code>)</li> <code>Copyright 2008 Google Inc.</code>)</li>
<li>a license boilerplate. Choose the appropriate boilerplate <li>license boilerplate if neccessary. Choose the appropriate
for the license used by the project (for example, boilerplate for the license used by the project (e.g.
Apache 2.0, BSD, LGPL, GPL)</li> Apache 2.0, BSD, LGPL, GPL)</li>
</ul> </ul>
</p> </p>
@ -838,42 +933,46 @@ Revision 2.24
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Instance variable pointers to objects derived from NSObject are Instance variables which are pointers to objects derived from NSObject
presumed to be retained, and should be documented as <b>weak</b> if are presumed to be retained, and should be either commented as weak or
they are not retained by the class. However, instance variables which declared with the <b>__weak</b> lifetime qualifier when applicable.
are labeled as IBOutlets are presumed to not be retained by the class, Similarly, declared properties must specify a <b>weak</b> or
and should be documented as <b>strong</b> if the class does retain <b>assign</b> property attribute if they are not retained by the
them. class. An exception is instance variables labeled as IBOutlets in Mac
software, which are presumed to not be retained.
</p> </p>
<p> <p>
Where instance variables are pointers to CoreFoundation, C++, and Where instance variables are pointers to CoreFoundation, C++, and
other non-Objective-C objects, they should always be documented in other non-Objective-C objects, they should always be declared with
comments as strong or weak. Be mindful that support for automatic C++ the __strong and __weak type modifiers to indicate which pointers are
objects encapsulated in Objective-C objects is disabled by default, as and are not retained. CoreFoundation and other non-Objective-C object
described <a href="http://chanson.livejournal.com/154253.html">here</a>. 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>
<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> <CODE_SNIPPET>
@interface MyDelegate : NSObject { @interface MyDelegate : NSObject {
@private @private
IBOutlet NSButton* okButton_; // normal NSControl IBOutlet NSButton *okButton_; // normal NSControl; implicitly weak on Mac only
IBOutlet NSMenu* myContextMenu_; // manually-loaded menu (strong)
AnObjcObject* doohickey_; // my doohickey 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... // non-NSObject pointers...
CWackyCPPClass* wacky_; // some cross-platform object (strong) __strong CWackyCPPClass *wacky_; // some cross-platform object
CFDictionaryRef* dict_; // (strong) __strong CFDictionaryRef *dict_;
} }
@property(strong, nonatomic) NSString *doohickey;
@property(weak, nonatomic) NSString *parent;
@end @end
</CODE_SNIPPET> </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> </p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -1171,7 +1270,52 @@ Revision 2.24
</BODY> </BODY>
</STYLEPOINT> </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> <SUMMARY>
<code>dealloc</code> should process instance variables in the same order <code>dealloc</code> should process instance variables in the same order
the <code>@interface</code> declares them, so it is easier for a reviewer the <code>@interface</code> declares them, so it is easier for a reviewer
@ -1452,60 +1596,6 @@ Revision 2.24
<code>retain</code>. <code>retain</code>.
</p> </p>
</SUBSECTION> </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"> <SUBSECTION title="Atomicity">
<p> <p>
Be aware of the overhead of properties. By default, all synthesized Be aware of the overhead of properties. By default, all synthesized
@ -1533,6 +1623,61 @@ Revision 2.24
</SUBSECTION> </SUBSECTION>
</BODY> </BODY>
</STYLEPOINT> </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> </CATEGORY>
@ -1601,7 +1746,7 @@ Revision 2.24
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 2.24 Revision 2.36
</p> </p>

357
pyguide.html
View File

@ -6,28 +6,33 @@
<LINK HREF="styleguide.css" type="text/css" rel="stylesheet"> <LINK HREF="styleguide.css" type="text/css" rel="stylesheet">
<SCRIPT language="javascript" type="text/javascript"> <SCRIPT language="javascript" type="text/javascript">
function ShowHideByName(bodyName, buttonName) { function GetElementsByName(name) {
var bodyElements; // Workaround a bug on old versions of opera.
var linkElement;
if (document.getElementsByName) { if (document.getElementsByName) {
bodyElements = document.getElementsByName(bodyName); return document.getElementsByName(name);
linkElement = document.getElementsByName('link-' + buttonName)[0];
} else { } else {
bodyElements = [document.getElementById(bodyName)]; return [document.getElementById(name)];
linkElement = document.getElementById('link-' + buttonName);
} }
}
/**
* @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) { 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 { } else {
var bodyElement = bodyElements[0]; var bodyElement = bodyElements[0];
var buttonElement; var buttonElement = GetElementsByName(buttonName)[0];
if (document.getElementsByName) { var isVisible = bodyElement.style.display != "none";
var buttonElements = document.getElementsByName(buttonName); if (getVisibility(isVisible)) {
buttonElement = buttonElements[0];
} else {
buttonElement = document.getElementById(buttonName);
}
if (bodyElement.style.display == "none" || bodyElement.style.display == "") {
bodyElement.style.display = "inline"; bodyElement.style.display = "inline";
linkElement.style.display = "block"; linkElement.style.display = "block";
buttonElement.innerHTML = '▽'; 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() { function ShowHideAll() {
var allButton; var allButton = GetElementsByName("show_hide_all_button")[0];
if (document.getElementsByName) {
var allButtons = document.getElementsByName("show_hide_all_button");
allButton = allButtons[0];
} else {
allButton = document.getElementById("show_hide_all_button");
}
if (allButton.innerHTML == '▽') { if (allButton.innerHTML == '▽') {
allButton.innerHTML = '▶'; allButton.innerHTML = '▶';
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '▶'); 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() { window.onload = function() {
// if the URL contains "?showall=y", expand the details of all children // if the URL contains "?showall=y", expand the details of all children
{ var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)");
var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)"); var showHideAllValue = showHideAllRegex.exec(window.location.href);
var showHideAllValue = showHideAllRegex.exec(window.location.href); if (showHideAllValue != null) {
if (showHideAllValue != null) { if (showHideAllValue[2] == "y") {
if (showHideAllValue[2] == "y") { SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '▽'); "inline", '▽');
} else { } else {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '▶'); 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> </SCRIPT>
</HEAD> </HEAD>
@ -100,7 +136,7 @@
<H1>Google Python Style Guide</H1> <H1>Google Python Style Guide</H1>
<p align="right"> <p align="right">
Revision 2.20 Revision 2.28
</p> </p>
<address> <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> <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"> <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 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=""> <DIV style="display:inline;" class="">
This style guide contains many details that are initially This style guide contains many details that are initially
hidden from view. They are marked by the triangle icon, which you 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> <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"> <SPAN class="link_button" id="link-pychecker__button" name="link-pychecker__button"><A href="?showone=pychecker#pychecker">
link 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=""> <DIV style="display:inline;" class="">
Run <code>pychecker</code> over your code. Run <code>pychecker</code> over your code.
</DIV> </DIV>
@ -255,7 +291,7 @@
<H3><A name="Imports" id="Imports">Imports</A></H3> <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"> <SPAN class="link_button" id="link-Imports__button" name="link-Imports__button"><A href="?showone=Imports#Imports">
link 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=""> <DIV style="display:inline;" class="">
Use <code>import</code>s for packages and modules only. Use <code>import</code>s for packages and modules only.
</DIV> </DIV>
@ -283,7 +319,7 @@
prefix. prefix.
<br> <br>
Use <code>from x import y as z</code> if two modules named 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. inconveniently long name.
</P> </P>
For example the module For example the module
@ -305,7 +341,7 @@
<H3><A name="Packages" id="Packages">Packages</A></H3> <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"> <SPAN class="link_button" id="link-Packages__button" name="link-Packages__button"><A href="?showone=Packages#Packages">
link 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=""> <DIV style="display:inline;" class="">
Import each module using the full pathname location of the module. Import each module using the full pathname location of the module.
</DIV> </DIV>
@ -340,7 +376,7 @@ from sound.effects import echo
<H3><A name="Exceptions" id="Exceptions">Exceptions</A></H3> <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"> <SPAN class="link_button" id="link-Exceptions__button" name="link-Exceptions__button"><A href="?showone=Exceptions#Exceptions">
link 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=""> <DIV style="display:inline;" class="">
Exceptions are allowed but must be used carefully. Exceptions are allowed but must be used carefully.
</DIV> </DIV>
@ -408,7 +444,7 @@ from sound.effects import echo
<H3><A name="Global_variables" id="Global_variables">Global variables</A></H3> <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"> <SPAN class="link_button" id="link-Global_variables__button" name="link-Global_variables__button"><A href="?showone=Global_variables#Global_variables">
link 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=""> <DIV style="display:inline;" class="">
Avoid global variables. Avoid global variables.
</DIV> </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> <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"> <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 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=""> <DIV style="display:inline;" class="">
Nested/local/inner classes and functions are fine. Nested/local/inner classes and functions are fine.
</DIV> </DIV>
@ -479,7 +515,7 @@ from sound.effects import echo
<H3><A name="List_Comprehensions" id="List_Comprehensions">List Comprehensions</A></H3> <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"> <SPAN class="link_button" id="link-List_Comprehensions__button" name="link-List_Comprehensions__button"><A href="?showone=List_Comprehensions#List_Comprehensions">
link 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=""> <DIV style="display:inline;" class="">
Okay to use for simple cases. Okay to use for simple cases.
</DIV> </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> <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"> <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 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=""> <DIV style="display:inline;" class="">
Use default iterators and operators for types that support them, Use default iterators and operators for types that support them,
like lists, dictionaries, and files. like lists, dictionaries, and files.
@ -593,7 +629,7 @@ from sound.effects import echo
<H3><A name="Generators" id="Generators">Generators</A></H3> <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"> <SPAN class="link_button" id="link-Generators__button" name="link-Generators__button"><A href="?showone=Generators#Generators">
link 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=""> <DIV style="display:inline;" class="">
Use generators as needed. Use generators as needed.
</DIV> </DIV>
@ -626,7 +662,7 @@ from sound.effects import echo
<H3><A name="Lambda_Functions" id="Lambda_Functions">Lambda Functions</A></H3> <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"> <SPAN class="link_button" id="link-Lambda_Functions__button" name="link-Lambda_Functions__button"><A href="?showone=Lambda_Functions#Lambda_Functions">
link 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=""> <DIV style="display:inline;" class="">
Okay for one-liners. Okay for one-liners.
</DIV> </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> <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"> <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 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=""> <DIV style="display:inline;" class="">
Okay in most cases. Okay in most cases.
</DIV> </DIV>
@ -727,7 +763,7 @@ from sound.effects import echo
<H3><A name="Properties" id="Properties">Properties</A></H3> <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"> <SPAN class="link_button" id="link-Properties__button" name="link-Properties__button"><A href="?showone=Properties#Properties">
link 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=""> <DIV style="display:inline;" class="">
Use properties for accessing or setting data where you would Use properties for accessing or setting data where you would
normally have used simple, lightweight accessor or setter methods. 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> <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"> <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 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=""> <DIV style="display:inline;" class="">
Use the "implicit" false if at all possible. Use the "implicit" false if at all possible.
</DIV> </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> <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"> <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 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=""> <DIV style="display:inline;" class="">
Use string methods instead of the <code>string</code> module Use string methods instead of the <code>string</code> module
where possible. Use function call syntax instead 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> <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"> <SPAN class="link_button" id="link-Lexical_Scoping__button" name="link-Lexical_Scoping__button"><A href="?showone=Lexical_Scoping#Lexical_Scoping">
link 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=""> <DIV style="display:inline;" class="">
Okay to use. Okay to use.
</DIV> </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> <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"> <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 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=""> <DIV style="display:inline;" class="">
Use decorators judiciously when there is a clear advantage. Use decorators judiciously when there is a clear advantage.
</DIV> </DIV>
@ -1080,7 +1116,7 @@ from sound.effects import echo
<H3><A name="Threading" id="Threading">Threading</A></H3> <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"> <SPAN class="link_button" id="link-Threading__button" name="link-Threading__button"><A href="?showone=Threading#Threading">
link 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=""> <DIV style="display:inline;" class="">
Do not rely on the atomicity of built-in types. Do not rely on the atomicity of built-in types.
</DIV> </DIV>
@ -1110,7 +1146,7 @@ from sound.effects import echo
<H3><A name="Power_Features" id="Power_Features">Power Features</A></H3> <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"> <SPAN class="link_button" id="link-Power_Features__button" name="link-Power_Features__button"><A href="?showone=Power_Features#Power_Features">
link 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=""> <DIV style="display:inline;" class="">
Avoid these features. Avoid these features.
</DIV> </DIV>
@ -1148,7 +1184,7 @@ from sound.effects import echo
<H3><A name="Semicolons" id="Semicolons">Semicolons</A></H3> <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"> <SPAN class="link_button" id="link-Semicolons__button" name="link-Semicolons__button"><A href="?showone=Semicolons#Semicolons">
link 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=""> <DIV style="display:inline;" class="">
Do not terminate your lines with semi-colons and do not use Do not terminate your lines with semi-colons and do not use
semi-colons to put two commands on the same line. 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> <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"> <SPAN class="link_button" id="link-Line_length__button" name="link-Line_length__button"><A href="?showone=Line_length#Line_length">
link 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=""> <DIV style="display:inline;" class="">
Maximum line length is <em>80 characters</em>. Maximum line length is <em>80 characters</em>.
</DIV> </DIV>
@ -1171,6 +1207,10 @@ from sound.effects import echo
earlier. earlier.
</p> </p>
<p>
Do not use backslash line continuation.
</p>
<p> <p>
Make use of Python's Make use of Python's
@ -1209,7 +1249,7 @@ from sound.effects import echo
<H3><A name="Parentheses" id="Parentheses">Parentheses</A></H3> <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"> <SPAN class="link_button" id="link-Parentheses__button" name="link-Parentheses__button"><A href="?showone=Parentheses#Parentheses">
link 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=""> <DIV style="display:inline;" class="">
Use parentheses sparingly. Use parentheses sparingly.
</DIV> </DIV>
@ -1241,7 +1281,7 @@ from sound.effects import echo
<H3><A name="Indentation" id="Indentation">Indentation</A></H3> <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"> <SPAN class="link_button" id="link-Indentation__button" name="link-Indentation__button"><A href="?showone=Indentation#Indentation">
link 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=""> <DIV style="display:inline;" class="">
Indent your code blocks with <em>4 spaces</em>. Indent your code blocks with <em>4 spaces</em>.
</DIV> </DIV>
@ -1278,7 +1318,7 @@ from sound.effects import echo
<H3><A name="Blank_Lines" id="Blank_Lines">Blank Lines</A></H3> <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"> <SPAN class="link_button" id="link-Blank_Lines__button" name="link-Blank_Lines__button"><A href="?showone=Blank_Lines#Blank_Lines">
link 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=""> <DIV style="display:inline;" class="">
Two blank lines between top-level definitions, one blank line Two blank lines between top-level definitions, one blank line
between method definitions. between method definitions.
@ -1297,7 +1337,7 @@ from sound.effects import echo
<H3><A name="Whitespace" id="Whitespace">Whitespace</A></H3> <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"> <SPAN class="link_button" id="link-Whitespace__button" name="link-Whitespace__button"><A href="?showone=Whitespace#Whitespace">
link 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=""> <DIV style="display:inline;" class="">
Follow standard typographic rules for the use of spaces around Follow standard typographic rules for the use of spaces around
punctuation. punctuation.
@ -1376,24 +1416,18 @@ from sound.effects import echo
<H3><A name="Shebang_Line" id="Shebang_Line">Shebang Line</A></H3> <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"> <SPAN class="link_button" id="link-Shebang_Line__button" name="link-Shebang_Line__button"><A href="?showone=Shebang_Line#Shebang_Line">
link 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=""> <DIV style="display:inline;" class="">
All <code>.py</code> files (except <code>__init__.py</code> package Most <code>.py</code> files do not need to start with a
files) should begin with a <code>#!</code> line. Start the main file of a binary with
<code>#!/usr/bin/python</code>.
<code>#!/usr/bin/python&lt;version&gt;</code>
shebang line.
</DIV> </DIV>
<DIV class=""><DIV class="stylepoint_body" name="Shebang_Line__body" id="Shebang_Line__body" style="display: none"> <DIV class=""><DIV class="stylepoint_body" name="Shebang_Line__body" id="Shebang_Line__body" style="display: none">
<p> <p>
Always use the most specific version that you can to ensure This line is used by the kernel to find the Python interpreter, but is
compatibility. For examples, if your program uses a language feature ignored by Python when importing modules. It is only necessary on a
that that first appeared in Python 2.4, use file that will be executed directly.
<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.
</p> </p>
</DIV></DIV> </DIV></DIV>
</DIV> </DIV>
@ -1402,7 +1436,7 @@ from sound.effects import echo
<H3><A name="Comments" id="Comments">Comments</A></H3> <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"> <SPAN class="link_button" id="link-Comments__button" name="link-Comments__button"><A href="?showone=Comments#Comments">
link 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=""> <DIV style="display:inline;" class="">
Be sure to use the right style for module, function, method and in-line Be sure to use the right style for module, function, method and in-line
comments. comments.
@ -1450,24 +1484,66 @@ from sound.effects import echo
<SPAN class="stylepoint_subsection">Functions and Methods</SPAN> <SPAN class="stylepoint_subsection">Functions and Methods</SPAN>
<p> <p>
Any function or method which is not both obvious and very short As used in this section "function" applies to methods, function, and
needs a doc string. Additionally, any externally accessible generators.
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:".
</p> </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> <DIV class=""><PRE>
<span class="external"></span>def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): <span class="external"></span>def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
<span class="external"> </span>"""Fetches rows from a Bigtable. <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> <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"> <SPAN class="link_button" id="link-Classes__button" name="link-Classes__button"><A href="?showone=Classes#Classes">
link 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=""> <DIV style="display:inline;" class="">
If a class inherits from no other base classes, explicitly inherit If a class inherits from no other base classes, explicitly inherit
from <code>object</code>. This also applies to nested classes. 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> <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"> <SPAN class="link_button" id="link-Strings__button" name="link-Strings__button"><A href="?showone=Strings#Strings">
link 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=""> <DIV style="display:inline;" class="">
Use the <code>%</code> operator for formatting strings, Use the <code>%</code> operator for formatting strings,
even when the parameters are all strings. Use your best judgement 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> <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"> <SPAN class="link_button" id="link-TODO_Comments__button" name="link-TODO_Comments__button"><A href="?showone=TODO_Comments#TODO_Comments">
link 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> </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=""> <DIV style="display:inline;" class="">
Use <code>TODO</code> comments for code that is temporary, a Use <code>TODO</code> comments for code that is temporary, a
short-term solution, or good-enough but not perfect. short-term solution, or good-enough but not perfect.
</DIV> </DIV>
<DIV class=""><DIV class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none"> <DIV class=""><DIV class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none">
<p> <p>
<code>TODO</code>s should include the string <code>TODO</code> in <code>TODO</code>s should include the string <code>TODO</code> in
all caps, followed by your 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>
name, e-mail address, or other <DIV class=""><PRE># TODO(kl@gmail.com): Use a "*" here for string repetition.
identifier # TODO(Zeke) Change this to use relations.</PRE></DIV>
in parentheses. A colon is optional. A comment explaining what there <p>
is to do is required. The main purpose is to have If your <code>TODO</code> is of the form "At a future date do
a consistent <code>TODO</code> format searchable by the person something" make sure that you either include a very specific
adding the comment (who can provide more details upon request). A date ("Fix by November 2009") or a very specific event
<code>TODO</code> is not a commitment to provide the fix yourself. ("Remove this code when all clients can handle XML responses.").
</p> </p>
</DIV></DIV>
<DIV class=""><PRE># TODO(kl@gmail.com): Drop the use of "has_key". </DIV>
# 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="">
<H3><A name="Imports_formatting" id="Imports_formatting">Imports formatting</A></H3> <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"> <SPAN class="link_button" id="link-Imports_formatting__button" name="link-Imports_formatting__button"><A href="?showone=Imports_formatting#Imports_formatting">
link 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=""> <DIV style="display:inline;" class="">
Imports should be on separate lines. Imports should be on separate lines.
</DIV> </DIV>
@ -1757,7 +1840,7 @@ Don'<span class="external"></span>t do this.
<H3><A name="Statements" id="Statements">Statements</A></H3> <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"> <SPAN class="link_button" id="link-Statements__button" name="link-Statements__button"><A href="?showone=Statements#Statements">
link 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=""> <DIV style="display:inline;" class="">
Generally only one statement per line. Generally only one statement per line.
</DIV> </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> <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"> <SPAN class="link_button" id="link-Access_Control__button" name="link-Access_Control__button"><A href="?showone=Access_Control#Access_Control">
link 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=""> <DIV style="display:inline;" class="">
If an accessor function would be trivial you should use public variables If an accessor function would be trivial you should use public variables
instead of accessor functions to avoid the extra cost of function 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> <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"> <SPAN class="link_button" id="link-Naming__button" name="link-Naming__button"><A href="?showone=Naming#Naming">
link 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=""> <DIV style="display:inline;" class="">
<code>module_name, package_name, ClassName, method_name, ExceptionName, <code>module_name, package_name, ClassName,
function_name, GLOBAL_VAR_NAME, instance_var_name, method_name, ExceptionName,
function_parameter_name, local_var_name.</code> function_name, GLOBAL_CONSTANT_NAME,
global_var_name, instance_var_name, function_parameter_name,
local_var_name.</code>
</DIV> </DIV>
<DIV class=""><DIV class="stylepoint_body" name="Naming__body" id="Naming__body" style="display: none"> <DIV class=""><DIV class="stylepoint_body" name="Naming__body" id="Naming__body" style="display: none">
<P class=""> <P class="">
@ -1958,7 +2043,7 @@ Don'<span class="external"></span>t do this.
<H3><A name="Main" id="Main">Main</A></H3> <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"> <SPAN class="link_button" id="link-Main__button" name="link-Main__button"><A href="?showone=Main#Main">
link 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=""> <DIV style="display:inline;" class="">
Even a file meant to be used as a script should be importable and a 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 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"> <p align="right">
Revision 2.20 Revision 2.28
</p> </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"> <SCRIPT language="javascript" type="text/javascript">
function ShowHideByName(bodyName, buttonName) { function GetElementsByName(name) {
var bodyElements; // Workaround a bug on old versions of opera.
var linkElement;
if (document.getElementsByName) { if (document.getElementsByName) {
bodyElements = document.getElementsByName(bodyName); return document.getElementsByName(name);
linkElement = document.getElementsByName('link-' + buttonName)[0];
} else { } else {
bodyElements = [document.getElementById(bodyName)]; return [document.getElementById(name)];
linkElement = document.getElementById('link-' + buttonName);
} }
}
/**
* @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) { 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 { } else {
var bodyElement = bodyElements[0]; var bodyElement = bodyElements[0];
var buttonElement; var buttonElement = GetElementsByName(buttonName)[0];
if (document.getElementsByName) { var isVisible = bodyElement.style.display != "none";
var buttonElements = document.getElementsByName(buttonName); if (getVisibility(isVisible)) {
buttonElement = buttonElements[0];
} else {
buttonElement = document.getElementById(buttonName);
}
if (bodyElement.style.display == "none" || bodyElement.style.display == "") {
bodyElement.style.display = "inline"; bodyElement.style.display = "inline";
linkElement.style.display = "block"; linkElement.style.display = "block";
buttonElement.innerHTML = '<xsl:value-of select="$hide_button_text"/>'; 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() { function ShowHideAll() {
var allButton; var allButton = GetElementsByName("show_hide_all_button")[0];
if (document.getElementsByName) {
var allButtons = document.getElementsByName("show_hide_all_button");
allButton = allButtons[0];
} else {
allButton = document.getElementById("show_hide_all_button");
}
if (allButton.innerHTML == '<xsl:value-of select="$hide_button_text"/>') { if (allButton.innerHTML == '<xsl:value-of select="$hide_button_text"/>') {
allButton.innerHTML = '<xsl:value-of select="$show_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"/>'); 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() { window.onload = function() {
// if the URL contains "?showall=y", expand the details of all children // if the URL contains "?showall=y", expand the details of all children
{ var showHideAllRegex = new RegExp("[\\?&amp;](showall)=([^&amp;#]*)");
var showHideAllRegex = new RegExp("[\\?&amp;](showall)=([^&amp;#]*)"); var showHideAllValue = showHideAllRegex.exec(window.location.href);
var showHideAllValue = showHideAllRegex.exec(window.location.href); if (showHideAllValue != null) {
if (showHideAllValue != null) { if (showHideAllValue[2] == "y") {
if (showHideAllValue[2] == "y") { SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '<xsl:value-of select="$hide_button_text"/>'); "inline", '<xsl:value-of select="$hide_button_text"/>');
} else { } else {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>'); 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> </SCRIPT>
</HEAD> </HEAD>
@ -214,9 +250,7 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
</xsl:variable> </xsl:variable>
<xsl:variable name="onclick_definition"> <xsl:variable name="onclick_definition">
<xsl:text>javascript:ShowHideByName('</xsl:text> <xsl:text>javascript:ShowHideByName('</xsl:text>
<xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$body_suffix"/> <xsl:value-of select="$stylepoint_name"/>
<xsl:text>','</xsl:text>
<xsl:value-of select="$buttonName"/>
<xsl:text>')</xsl:text> <xsl:text>')</xsl:text>
</xsl:variable> </xsl:variable>
<SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}"> <SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}">