mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
Update C++ style guide to 3.199:
- 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:
parent
8a95ecca27
commit
e33361fcd3
83
cppguide.xml
83
cppguide.xml
|
@ -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 <sys/types.h>
|
#include <sys/types.h>
|
||||||
#include <unistd.h>
|
#include <unistd.h>
|
||||||
|
|
||||||
#include <hash_map>
|
#include <hash_map>
|
||||||
#include <vector>
|
#include <vector>
|
||||||
|
|
||||||
|
@ -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&</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&</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&</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—for example by removing
|
coding practices that hamper readability—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>&&</code> logical AND operators are at the
|
the <code>&&</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>&&</code> and
|
punctuation operators, such as <code>&&</code> and
|
||||||
|
@ -4550,7 +4565,7 @@ Tashana Landray
|
||||||
<HR/>
|
<HR/>
|
||||||
|
|
||||||
<p align="right">
|
<p align="right">
|
||||||
Revision 3.188
|
Revision 3.199
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
|
1641
javascriptguide.xml
1641
javascriptguide.xml
File diff suppressed because it is too large
Load Diff
387
objcguide.xml
387
objcguide.xml
|
@ -4,7 +4,7 @@
|
||||||
|
|
||||||
<p align="right">
|
<p align="right">
|
||||||
|
|
||||||
Revision 2.24
|
Revision 2.36
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
@ -129,8 +129,8 @@ 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.
|
||||||
|
@ -144,26 +144,27 @@ Revision 2.24
|
||||||
// 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_|.
|
// Gets and sets |bar_|.
|
||||||
- (NSString *)foo;
|
- (NSString *)bar;
|
||||||
- (void)setFoo:(NSString *)newFoo;
|
- (void)setBar:(NSString *)bar;
|
||||||
|
|
||||||
// Does some work on |blah| and returns YES if the work was completed
|
// Does some work with |blah| and returns YES if the work was completed
|
||||||
// successfuly, and NO otherwise.
|
// successfully, and NO otherwise.
|
||||||
- (BOOL)doWorkWithString:(NSString *)blah;
|
- (BOOL)doWorkWithBlah:(NSString *)blah;
|
||||||
|
|
||||||
@end
|
@end
|
||||||
</CODE_SNIPPET>
|
</CODE_SNIPPET>
|
||||||
|
@ -177,51 +178,51 @@ Revision 2.24
|
||||||
|
|
||||||
<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;
|
||||||
}
|
}
|
||||||
|
@ -232,7 +233,7 @@ Revision 2.24
|
||||||
<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<NSWindowDelegate> {
|
@interface MyProtocoledClass : NSObject<NSWindowDelegate> {
|
||||||
|
@ -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>
|
||||||
|
|
||||||
|
|
||||||
|
|
297
pyguide.html
297
pyguide.html
|
@ -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 ShowHideAll() {
|
function ShowHideByName(namePrefix) {
|
||||||
var allButton;
|
ChangeVisibility(namePrefix, function(old) { return !old; });
|
||||||
if (document.getElementsByName) {
|
|
||||||
var allButtons = document.getElementsByName("show_hide_all_button");
|
|
||||||
allButton = allButtons[0];
|
|
||||||
} else {
|
|
||||||
allButton = document.getElementById("show_hide_all_button");
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
function ShowByName(namePrefix) {
|
||||||
|
ChangeVisibility(namePrefix, function() { return true; });
|
||||||
|
}
|
||||||
|
|
||||||
|
function ShowHideAll() {
|
||||||
|
var allButton = GetElementsByName("show_hide_all_button")[0];
|
||||||
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, "inline", '▽');
|
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
|
||||||
|
"inline", '▽');
|
||||||
} else {
|
} else {
|
||||||
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '▶');
|
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
|
||||||
|
"none", '▶');
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
|
var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
|
||||||
var showOneValue = showOneRegex.exec(window.location.href);
|
var showOneValue = showOneRegex.exec(window.location.href);
|
||||||
if (showOneValue != null) {
|
if (showOneValue) {
|
||||||
var body_name = showOneValue[2] + '__body';
|
ShowHideByName(showOneValue[2]);
|
||||||
var button_name = showOneValue[2] + '__button';
|
|
||||||
ShowHideByName(body_name, button_name);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
}
|
|
||||||
|
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<version></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,7 +1757,7 @@ 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.
|
||||||
|
@ -1689,19 +1765,26 @@ Don'<span class="external"></span>t do this.
|
||||||
<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
|
name, e-mail address, or other
|
||||||
identifier
|
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
|
in parentheses. A colon is optional. A comment explaining what there
|
||||||
is to do is required. The main purpose is to have
|
is to do is required. The main purpose is to have
|
||||||
a consistent <code>TODO</code> format searchable by the person
|
a consistent <code>TODO</code> format that can be searched to find the
|
||||||
adding the comment (who can provide more details upon request). A
|
person who can provide more details upon request. A
|
||||||
<code>TODO</code> is not a commitment to provide the fix yourself.
|
<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>
|
</p>
|
||||||
|
|
||||||
<DIV class=""><PRE># TODO(kl@gmail.com): Drop the use of "has_key".
|
<DIV class=""><PRE># TODO(kl@gmail.com): Use a "*" here for string repetition.
|
||||||
# TODO(Zeke) change this to use relations.</PRE></DIV>
|
# TODO(Zeke) Change this to use relations.</PRE></DIV>
|
||||||
<p>
|
<p>
|
||||||
If your <code>TODO</code> is of the form "At a future date do
|
If your <code>TODO</code> is of the form "At a future date do
|
||||||
something" make sure that you either include a very specific
|
something" make sure that you either include a very specific
|
||||||
|
@ -1714,7 +1797,7 @@ Don'<span class="external"></span>t do this.
|
||||||
<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>
|
||||||
|
|
||||||
|
|
||||||
|
|
102
styleguide.xsl
102
styleguide.xsl
|
@ -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 ShowHideAll() {
|
function ShowHideByName(namePrefix) {
|
||||||
var allButton;
|
ChangeVisibility(namePrefix, function(old) { return !old; });
|
||||||
if (document.getElementsByName) {
|
|
||||||
var allButtons = document.getElementsByName("show_hide_all_button");
|
|
||||||
allButton = allButtons[0];
|
|
||||||
} else {
|
|
||||||
allButton = document.getElementById("show_hide_all_button");
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
function ShowByName(namePrefix) {
|
||||||
|
ChangeVisibility(namePrefix, function() { return true; });
|
||||||
|
}
|
||||||
|
|
||||||
|
function ShowHideAll() {
|
||||||
|
var allButton = GetElementsByName("show_hide_all_button")[0];
|
||||||
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 && 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 = '<xsl:value-of select="$body_suffix"/>';
|
||||||
|
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, "inline", '<xsl:value-of select="$hide_button_text"/>');
|
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
|
||||||
|
"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("[\\?&](showone)=([^&#]*)");
|
var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
|
||||||
var showOneValue = showOneRegex.exec(window.location.href);
|
var showOneValue = showOneRegex.exec(window.location.href);
|
||||||
if (showOneValue != null) {
|
if (showOneValue) {
|
||||||
var body_name = showOneValue[2] + '<xsl:value-of select="$body_suffix"/>';
|
ShowHideByName(showOneValue[2]);
|
||||||
var button_name = showOneValue[2] + '<xsl:value-of select="$button_suffix"/>';
|
|
||||||
ShowHideByName(body_name, button_name);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
}
|
|
||||||
|
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}">
|
||||||
|
|
Loading…
Reference in New Issue
Block a user