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

Update C++ style guide to 3.231:

Browse Source 
- Clarify that sentence-like non-sentence comments are permitted.
 - Note that older code with incorrect #include ordering should be fixed.
 - Revamp the section on default function arguments.
 - Avoid explicitly recommending Init() methods.
 - C++11: permit "auto".
 - C++11: permit ">>" in place of "> >".
 - C++11: permit range-based "for".
 - C++11: permit variadic macros (already permitted as a C++03 extension).
 - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03
   extension).
 - Reflect the revised copyright and author line policy: copyright notices are
   not required, but license boilerplate may still be used (and generally
   contains a copyright notice). Author lines are not required.
 - C++11: permit new features in <algorithm> and the portion of <numeric> that
   does not require initializer lists.
 - Revise rules on forward declarations: explicitly forbid forward-declared
   functions, do not mandate forward declarations, discourage forward-declared
   templates.
 - Remove the rule requiring "const" qualifiers for member functions to be
   on the same line as the closing parenthesis of the parameter list.
 - Fix typo: "unnamed namespaces."
 - C++11: permit local types as template parameters.
 - Fix typo: "unfamiliar."
 - Relax RTTI rules to permit its use, but warn about its abuse.
 - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer
   more generically to null pointers.
 - Remove the "don't go crazy with const" rule.
 - Fix typo: "dir/foo2" should bee "dir2/foo2."
 - Remove reference to a specific GCC version.

Update Objective-C style guide to 2.48:
 - Revise method declaration and invocation formatting rules for long names.
 - Reflect the revised copyright and author line policy: copyright notices are
   not required, but license boilerplate may still be used (and generally
   contains a copyright notice). Author lines are not required. Top-of-file
   comments are not required.
 - Fix dead link in the "nil Checks" section.
 - Cover ARC.
 - Specify that @private is only required for instance variables in header
   files.
 - Permit NSNumber literals.
 - Change the naming convention for instance variables from trailing underscore
   to leading underscore, allowing a wide exception for existing code and
   projects.
 - Fix description of BOOL with respect to its signedness.

Update Python style guide to 2.45:
 - Recommend "pylint: disable" over "pylint: disable-msg."
 - Fix case-sensitive anchor.
 - Provide a better explanation of the problems with catch-all "except:."
 - Permit "map" and "filter" in absence of inlined lambdas.

Update JavaScript style guide to 2.64:
 - Clarify rules for requiring and providing inner dependencies on classes.
 - Clarify semicolons for functions.
 - Note proper namespace and filename casing.
 - Fix typos: "@extends."
 - Permit parentheses to be omitted on unions.
 - Don't require method descriptions when obvious.
 - "in" is a keyword, put it in <code>.
 - New "Aliasing with goog.scope" section.
 - Rewrite the "Constants" section.
 - Remove the recommendation to use join() to build strings.
 - Add the "@expose" annotation.
 - Fix the "@suppress" example.
 - Remove reference alternate cast syntax.
 - Reflect the revised copyright and author line policy: copyright notices are
   not required, but license boilerplate may still be used (and generally
   contains a copyright notice). Author lines are not required.
 - Say that "use strict" is not required.
 - Fix links to "optional" section.
 - Rewrite "JavaScript Types" section.
 - Fix typos: "parameterizes," "converted."
 - Prefer in-constructor field initialization.
 - Add a section on "delete" and null-assignment.
 - Add a note about optional JSDoc comments on enum values.
 - State explicitly that dot operators belong at the ends of lines.
 - Add "@dict" and "@struct" annotations.
 - Add links to the JavaScript Types section.
 - Require (rather than encourage) compiling.

Update HTML/CSS style guide to 2.19:
 - Rephrased quotation guidelines.
 - Updated W3C I18N article reference.
 - Fixed revision number.

Update styleguide.xsl to 1.34:
 - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a
   named anchor within a section, as used by the JavaScript style guide.
This commit is contained in:
mark@chromium.org 2012-11-28 20:26:27 +00:00
parent 1407ba71db
commit c8c76a2389
6 changed files with 1209 additions and 647 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

589
cppguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 3.199 Revision 3.231
</p> </p>
@ -145,80 +145,71 @@ Tashana Landray
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Header File Dependencies"> <STYLEPOINT title="Forward Declarations">
<SUMMARY> <SUMMARY>
Don't use an <code>#include</code> when a forward declaration You may forward declare ordinary classes in order to avoid
would suffice. unnecessary <code>#include</code>s.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <DEFINITION>
When you include a header file you introduce a dependency that A "forward declaration" is a declaration of a class, function,
will cause your code to be recompiled whenever the header file or template without an associated definition. <code>#include</code>
changes. If your header file includes other header files, any lines can often be replaced with forward declarations of whatever
change to those files will cause any code that includes your symbols are actually used by the client code.
header to be recompiled. Therefore, we prefer to minimize </DEFINITION>
includes, particularly includes of header files in other <PROS>
header files. <ul>
</p> <li>Unnecessary <code>#include</code>s force the compiler to open
<p> more files and process more input.</li>
You can significantly reduce the number of header files you <li>They can also force your code to be recompiled more often, due
need to include in your own header files by using forward to changes in the header.</li>
declarations. For example, if your header file uses the </ul>
<code>File</code> class in ways that do not require access to </PROS>
the declaration of the <code>File</code> class, your header <CONS>
file can just forward declare <code>class File;</code> instead <ul>
of having to <code>#include "file/base/file.h"</code>. <li>It can be difficult to determine the correct form of a
</p> forward declaration in the presence of features like templates,
<p> typedefs, default parameters, and using declarations.</li>
How can we use a class <code>Foo</code> in a header file <li>It can be difficult to determine whether a forward declaration
without access to its definition? or a full <code>#include</code> is needed for a given piece of code,
</p> particularly when implicit conversion operations are involved. In
<ul> extreme cases, replacing an <code>#include</code> with a forward
<li> We can declare data members of type <code>Foo*</code> or declaration can silently change the meaning of code.</li>
<code>Foo&amp;</code>. <li>Forward declaring multiple symbols from a header can be more
</li> verbose than simply <code>#include</code>ing the header.</li>
<li> We can declare (but not define) functions with arguments, <li>Forward declarations of functions and templates can prevent
and/or return values, of type <code>Foo</code>. (One the header owners from making otherwise-compatible changes to
exception is if an argument <code>Foo</code> their APIs; for example, widening a parameter type, or adding
or <code>const Foo&amp;</code> has a a template parameter with a default value.</li>
non-<code>explicit</code>, one-argument constructor, <li>Forward declaring symbols from namespace <code>std::</code>
usually yields undefined behavior.</li>
in which case we need the full definition to support <li>Structuring code to enable forward declarations (e.g.
automatic type conversion.) using pointer members instead of object members) can make the
</li> code slower and more complex.</li>
<li> We can declare static data members of type <li>The practical efficiency benefits of forward declarations are
<code>Foo</code>. This is because static data members unproven.</li>
are defined outside the class definition. </ul>
</li> </CONS>
</ul> <DECISION>
<p> <ul>
On the other hand, you must include the header file for <li>When using a function declared in a header file, always
<code>Foo</code> if your class subclasses <code>Foo</code> or <code>#include</code> that header.</li>
has a data member of type <code>Foo</code>. <li>When using a class template, prefer to <code>#include</code> its
</p> header file.</li>
<p> <li>When using an ordinary class, relying on a forward declaration
Sometimes it makes sense to have pointer (or better, is OK, but be wary of situations where a forward declaration may
<code>scoped_ptr</code>) be insufficient or incorrect; when in doubt, just
members instead of object members. However, this complicates code <code>#include</code> the appropriate header.</li>
readability and imposes a performance penalty, so avoid doing <li>Do not replace data members with pointers just to avoid an
this transformation if the only purpose is to minimize includes <code>#include</code>.</li>
in header files. </ul>
</p> Always <code>#include</code> the file that actually provides the
<p> declarations/definitions you need; do not rely on the symbol being
Of course, <code>.cc</code> files typically do require the brought in transitively via headers not directly included. One
definitions of the classes they use, and usually have to exception is that <code>myfile.cc</code> may rely on
include several header files. <code>#include</code>s and forward declarations from its corresponding
</p> header file <code>myfile.h</code>.
<SUBSECTION title="Note:"> </DECISION>
If you use a symbol <code>Foo</code> in your source file, you
should bring in a definition for <code>Foo</code> yourself,
either via an #include or via a forward declaration. Do not
depend on the symbol being brought in transitively via headers
not directly included. One exception is if <code>Foo</code>
is used in <code>myfile.cc</code>, it's ok to #include (or
forward-declare) <code>Foo</code> in <code>myfile.h</code>,
instead of <code>myfile.cc</code>.
</SUBSECTION>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -367,7 +358,7 @@ Tashana Landray
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
In <code><var>dir/foo</var>.cc</code> or <code><var>dir/foo_test</var>.cc</code>, In <code><var>dir/foo</var>.cc</code> or <code><var>dir/foo_test</var>.cc</code>,
whose main purpose is to implement or test the stuff in whose main purpose is to implement or test the stuff in
<code><var>dir2/foo2</var>.h</code>, order your includes as <code><var>dir2/foo2</var>.h</code>, order your includes as
follows: follows:
</p> </p>
@ -382,7 +373,7 @@ Tashana Landray
<code>.h</code> files.</li> <code>.h</code> files.</li>
</ol> </ol>
<p> <p>
With the preferred ordering, if <code><var>dir/foo2</var>.h</code> With the preferred ordering, if <code><var>dir2/foo2</var>.h</code>
omits any necessary includes, the build of omits any necessary includes, the build of
<code><var>dir/foo</var>.cc</code> or <code><var>dir/foo</var>.cc</code> or
<code><var>dir/foo</var>_test.cc</code> will break. <code><var>dir/foo</var>_test.cc</code> will break.
@ -399,8 +390,9 @@ Tashana Landray
</p> </p>
<p> <p>
Within each section it is nice to order the includes Within each section the includes should be ordered alphabetically.
alphabetically. Note that older code might not conform to this rule and should be
fixed when convenient.
</p> </p>
<p> <p>
For example, the includes in For example, the includes in
@ -461,7 +453,7 @@ Tashana Landray
(also hierarchical) name axis provided by classes. (also hierarchical) name axis provided by classes.
</p> </p>
<p> <p>
Use of unnamed spaces in header files can easily cause Use of unnamed namespaces in header files can easily cause
violations of the C++ One Definition Rule (ODR). violations of the C++ One Definition Rule (ODR).
</p> </p>
</CONS> </CONS>
@ -840,9 +832,8 @@ Tashana Landray
<STYLEPOINT title="Doing Work in Constructors"> <STYLEPOINT title="Doing Work in Constructors">
<SUMMARY> <SUMMARY>
In general, constructors should merely set member variables to their Avoid doing complex initialization in constructors (in particular,
initial values. Any complex initialization should go in an explicit initialization that can fail or that requires virtual method calls).
<code>Init()</code> method.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<DEFINITION> <DEFINITION>
@ -882,10 +873,9 @@ Tashana Landray
</ul> </ul>
</CONS> </CONS>
<DECISION> <DECISION>
If your object requires non-trivial initialization, consider Constructors should never call virtual functions or attempt to raise
having an explicit <code>Init()</code> method. In particular, non-fatal failures. If your object requires non-trivial
constructors should not call virtual functions, attempt to raise initialization, consider using a factory function or <code>Init()</code> method.
errors, access potentially uninitialized global variables, etc.
</DECISION> </DECISION>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -1551,7 +1541,7 @@ Tashana Landray
Defining a parameter as reference avoids ugly code like Defining a parameter as reference avoids ugly code like
<code>(*pval)++</code>. Necessary for some applications like <code>(*pval)++</code>. Necessary for some applications like
copy constructors. Makes it clear, unlike with pointers, that copy constructors. Makes it clear, unlike with pointers, that
<code>NULL</code> is not a possible value. a null pointer is not a possible value.
</PROS> </PROS>
<CONS> <CONS>
References can be confusing, as they have value syntax but References can be confusing, as they have value syntax but
@ -1577,10 +1567,10 @@ Tashana Landray
However, there are some instances where using <code>const T*</code> However, there are some instances where using <code>const T*</code>
is preferable to <code>const T&amp;</code> for input parameters. For is preferable to <code>const T&amp;</code> for input parameters. For
example: example:
<ul>
You want to pass in NULL. <li>You want to pass in a null pointer.</li>
<li>The function saves a pointer or reference to the input.</li>
The function saves a pointer or reference to the input. </ul>
Remember that most of the time input parameters are going to be Remember that most of the time input parameters are going to be
@ -1643,35 +1633,47 @@ Tashana Landray
<STYLEPOINT title="Default Arguments"> <STYLEPOINT title="Default Arguments">
<SUMMARY> <SUMMARY>
We do not allow default function parameters, except in We do not allow default function parameters, except in limited
a few uncommon situations explained below. situations as explained below. Simulate them with function
overloading instead, if appropriate.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<PROS> <PROS>
Often you have a function that uses lots of default values, Often you have a function that uses default values, but
but occasionally you want to override the defaults. Default occasionally you want to override the defaults. Default
parameters allow an easy way to do this without having to parameters allow an easy way to do this without having to
define many functions for the rare exceptions. define many functions for the rare exceptions. Compared to
overloading the function, default arguments have a cleaner
syntax, with less boilerplate and a clearer distinction
between 'required' and 'optional' arguments.
</PROS> </PROS>
<CONS> <CONS>
People often figure out how to use an Function pointers are confusing in the presence of default
API by looking at existing code that uses it. arguments, since the function signature often doesn't match
Default parameters are more difficult to maintain because the call signature. Adding a default argument to an existing
copy-and-paste from previous code may not reveal all the function changes its type, which can cause problems with code
parameters. Copy-and-pasting of code segments can cause major taking its address. Adding function overloads avoids these
problems when the default arguments are not appropriate for problems. In addition, default parameters may result in
the new code. bulkier code since they are replicated at every call-site --
as opposed to overloaded functions, where "the default"
appears only in the function definition.
</CONS> </CONS>
<DECISION> <DECISION>
<p> <p>
Except as described below, we require all arguments to be While the cons above are not that onerous, they still
explicitly specified, to force programmers to consider the API outweigh the (small) benefits of default arguments over
and the values they are passing for each argument rather than function overloading. So except as described below, we
silently accepting defaults they may not be aware of. require all arguments to be explicitly specified.
</p> </p>
<p> <p>
One specific exception is when default arguments are used to One specific exception is when the function is a static
simulate variable-length argument lists. function (or in an unnamed namespace) in a .cc file. In
this case, the cons don't apply since the function's use is
so localized.
</p>
<p>
Another specific exception is when default arguments are
used to simulate variable-length argument lists.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
// Support up to 4 params by using a default empty AlphaNum. // Support up to 4 params by using a default empty AlphaNum.
@ -1851,57 +1853,107 @@ Tashana Landray
<STYLEPOINT title="Run-Time Type Information (RTTI)"> <STYLEPOINT title="Run-Time Type Information (RTTI)">
<SUMMARY> <SUMMARY>
We do not use Run Time Type Information (RTTI). Avoid using Run Time Type Information (RTTI).
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<DEFINITION> <DEFINITION>
RTTI allows a programmer to query the C++ class of an RTTI allows a programmer to query the C++ class of an
object at run time. object at run time. This is done by use of <code>typeid</code> or
<code>dynamic_cast</code>.
</DEFINITION> </DEFINITION>
<CONS>
<p>
Querying the type of an object at run-time frequently means a
design problem. Needing to know the type of an
object at runtime is often an indication that
the design of your class hierarchy is flawed.
</p>
<p>
Undisciplined use of RTTI makes code hard to maintain. It can
lead to type-based decision trees or switch statements scattered
throughout the code, all of which must be examined when making
further changes.
</p>
</CONS>
<PROS> <PROS>
<p> <p>
It is useful in some unittests. For example, it is useful in The standard alternatives to RTTI (described below) require
tests of factory classes where the test has to verify that a modification or redesign of the class hierarchy in question.
newly created object has the expected dynamic type. Sometimes such modifications are infeasible or undesirable,
particularly in widely-used or mature code.
</p> </p>
<p> <p>
In rare circumstances, it is useful even outside of RTTI can be useful in some unit tests. For example, it is useful in
tests. tests of factory classes where the test has to verify that a
newly created object has the expected dynamic type. It is also
useful in managing the relationship between objects and their mocks.
</p> </p>
<p>
RTTI is useful when considering multiple abstract objects. Consider
<CODE_SNIPPET>
bool Base::Equal(Base* other) = 0;
bool Derived::Equal(Base* other) {
Derived* that = dynamic_cast&lt;Derived*&gt;(other);
if (that == NULL)
return false;
...
}
</CODE_SNIPPET>
</p>
</PROS> </PROS>
<CONS>
A query of type during run-time typically means a
design problem. If you need to know the type of an
object at runtime, that is often an indication that
you should reconsider the design of your class.
</CONS>
<DECISION> <DECISION>
<p> <p>
Do not use RTTI, except in unittests. If you find yourself RTTI has legitimate uses but is prone to abuse, so you must
in need of writing code that behaves differently based on be careful when using it. You may use it freely
the class of an object, consider one of the alternatives to in unittests, but avoid it when possible in other code.
querying the type. In particular, think twice before using RTTI in new code.
If you find yourself needing to write code that behaves differently
based on the class of an object, consider one of the following
alternatives to querying the type:
<ul>
<li>
Virtual methods are the preferred way of executing different
code paths depending on a specific subclass type. This puts
the work within the object itself.
</li>
<li>
If the work belongs outside the object and instead in some
processing code, consider a double-dispatch solution, such
as the Visitor design pattern. This allows a facility
outside the object itself to determine the type of class
using the built-in type system.
</li>
</ul>
</p> </p>
<p> <p>
Virtual methods are the preferred way of executing different When the logic of a program guarantees that a given instance
code paths depending on a specific subclass type. This puts of a base class is in fact an instance of a particular derived class,
the work within the object itself. then a <code>dynamic_cast</code> may be used freely on the object.
</p>
<p>
If the work belongs outside the object and instead in some
processing code, consider a double-dispatch solution, such
as the Visitor design pattern. This allows a facility
outside the object itself to determine the type of class
using the built-in type system.
</p>
<p>
If you think you truly cannot use those ideas,
you may use RTTI. But think twice Usually one can use a
about it. :-) Then think twice again. <code>static_cast</code> as an alternative in such situations.
</p>
<p>
Decision trees based on type are a strong indication that your
code is on the wrong track.
<BAD_CODE_SNIPPET>
if (typeid(*data) == typeid(D1)) {
...
} else if (typeid(*data) == typeid(D2)) {
...
} else if (typeid(*data) == typeid(D3)) {
...
</BAD_CODE_SNIPPET>
Code such as this usually breaks when additional subclasses are
added to the class hierarchy. Moreover, when properties of a subclass
change, it is difficult to find and modify all the affected code segments.
</p>
<p>
Do not hand-implement an RTTI-like workaround. The arguments Do not hand-implement an RTTI-like workaround. The arguments
against RTTI apply just as much to workarounds like class against RTTI apply just as much to workarounds like class
hierarchies with type tags. hierarchies with type tags. Moreover, workarounds disguise your
true intent.
</p> </p>
</DECISION> </DECISION>
</BODY> </BODY>
@ -1951,13 +2003,11 @@ Tashana Landray
other pointer types. Use this only if you know what you are other pointer types. Use this only if you know what you are
doing and you understand the aliasing issues. doing and you understand the aliasing issues.
</li>
<li> Do not use <code>dynamic_cast</code> except in test code.
If you need to know type information at runtime in this way
outside of a unittest, you probably have a <A HREF="#Run-Time_Type_Information__RTTI_">design
flaw</A>.
</li> </li>
</ul> </ul>
<p> See the <a href="#Run-Time_Type_Information__RTTI_">RTTI section</a>
for guidance on the use of <code>dynamic_cast</code>.
</p>
</DECISION> </DECISION>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -2108,8 +2158,7 @@ Tashana Landray
<STYLEPOINT title="Use of const"> <STYLEPOINT title="Use of const">
<SUMMARY> <SUMMARY>
We strongly recommend that you use <code>const</code> whenever Use <code>const</code> whenever it makes sense.
it makes sense to do so.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<DEFINITION> <DEFINITION>
@ -2163,13 +2212,6 @@ Tashana Landray
construction. construction.
</li> </li>
</ul> </ul>
<p>
However, do not go crazy with <code>const</code>. Something like
<code>const int * const * const x;</code> is likely
overkill, even if it accurately describes how const x is.
Focus on what's really useful to know: in this case,
<code>const int** x</code> is probably sufficient.
</p>
<p> <p>
The <code>mutable</code> keyword is allowed but is unsafe The <code>mutable</code> keyword is allowed but is unsafe
when used with threads, so thread safety should be carefully when used with threads, so thread safety should be carefully
@ -2183,9 +2225,11 @@ Tashana Landray
readable because it's more consistent: it keeps the rule readable because it's more consistent: it keeps the rule
that <code>const</code> always follows the object it's that <code>const</code> always follows the object it's
describing. However, this consistency argument doesn't describing. However, this consistency argument doesn't
apply in this case, because the "don't go crazy" dictum apply in codebases with few deeply-nested pointer
eliminates most of the uses you'd have to be consistent with. expressions since most <code>const</code> expressions have
only one <code>const</code>, and it applies to the
underlying value. In such cases, there's no consistency to
maintain.
Putting the <code>const</code> first is arguably more readable, Putting the <code>const</code> first is arguably more readable,
since it follows English in putting the "adjective" since it follows English in putting the "adjective"
(<code>const</code>) before the "noun" (<code>int</code>). (<code>const</code>) before the "noun" (<code>int</code>).
@ -2494,10 +2538,11 @@ Tashana Landray
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="0 and NULL"> <STYLEPOINT title="0 and nullptr/NULL">
<SUMMARY> <SUMMARY>
Use <code>0</code> for integers, <code>0.0</code> for reals, Use <code>0</code> for integers, <code>0.0</code> for reals,
<code>NULL</code> for pointers, and <code>'\0'</code> for chars. <code>nullptr</code> (or <code>NULL</code>) for pointers,
and <code>'\0'</code> for chars.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -2505,13 +2550,17 @@ Tashana Landray
This is not controversial. This is not controversial.
</p> </p>
<p> <p>
For pointers (address values), there is a choice between <code>0</code> For pointers (address values), there is a choice between <code>0</code>
and <code>NULL</code>. Bjarne Stroustrup prefers an unadorned and <code>NULL</code> (and, for C++11, <code>nullptr</code>).
<code>0</code>. We prefer <code>NULL</code> because it looks like a For projects that allow C++11 features, use <code>nullptr</code>.
pointer. In fact, some C++ compilers, such as gcc 4.1.0, provide special For C++03 projects, we prefer <code>NULL</code> because it looks like a
definitions of <code>NULL</code> which enable them to give useful pointer. In fact, some C++ compilers provide special definitions of
warnings, particularly in situations where <code>sizeof(NULL)</code> <code>NULL</code> which enable them to give useful warnings,
is not equal to <code>sizeof(0)</code>. particularly in situations where <code>sizeof(NULL)</code> is not equal
to <code>sizeof(0)</code>.
</p> </p>
<p> <p>
Use <code>'\0'</code> for chars. Use <code>'\0'</code> for chars.
@ -2545,6 +2594,102 @@ Tashana Landray
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="auto">
<SUMMARY>
Use <code>auto</code> to avoid type names that are just clutter.
Continue to use manifest type declarations when it helps readability,
and never use <code>auto</code> for anything but local variables.
</SUMMARY>
<BODY>
<DEFINITION>
In C++11, a variable whose type is given as <code>auto</code> will be given
a type that matches that of the expression used to initialize
it. You can use <code>auto</code> either to initialize a
variable by copying, or to bind a reference.
<CODE_SNIPPET>
vector&lt;string&gt; v;
...
auto s1 = v[0]; // Makes a copy of v[0].
const auto&amp; s2 = v[0]; // s2 is a reference to v[0].
</CODE_SNIPPET>
</DEFINITION>
<PROS>
<p>
C++ type names can sometimes be long and cumbersome,
especially when they involve templates or namespaces. In a statement like
<CODE_SNIPPET>
sparse_hash_map&lt;string, int&gt;::iterator iter = m.find(val);
</CODE_SNIPPET>
the return type is hard to read, and obscures the primary
purpose of the statement. Changing it to
<CODE_SNIPPET>
auto iter = m.find(val);
</CODE_SNIPPET>
makes it more readable.
</p>
<p>
Without <code>auto</code> we are sometimes forced to write a
type name twice in the same expression, adding no value
for the reader, as in
<CODE_SNIPPET>
diagnostics::ErrorStatus* status = new diagnostics::ErrorStatus("xyz");
</CODE_SNIPPET>
</p>
<p>
Using <code>auto</code> makes it easier to use intermediate
variables when appropriate, by reducing the burden of writing
their types explicitly.
</p>
</PROS>
<CONS>
<p>Sometimes code is clearer when types are manifest, especially when
a variable's initialization depends on things that were declared
far away. In an expression like
<CODE_SNIPPET>
auto i = x.Lookup(key);
</CODE_SNIPPET>
it may not be obvious what <code>i</code>'s type is, if <code>x</code>
was declared hundreds of lines earlier.
</p>
<p>Programmers have to understand the difference between <code>auto</code>
and <code>const auto&amp;</code> or they'll get copies when
they didn't mean to.
</p>
<p>The interaction between <code>auto</code> and C++11
brace-initialization can be confusing. (C++11 brace-initialization
isn't an approved feature, but this may become relevant when and
if it is permitted.) The declarations
<CODE_SNIPPET>
auto x(3); // Note: parentheses.
auto y{3}; // Note: curly braces.
</CODE_SNIPPET>
mean different things &#8212; <code>x</code> is
an <code>int</code>, while <code>y</code> is
an <code>initializer_list</code>. The same applies to other
normally-invisible proxy types.
</p>
<p>If an <code>auto</code> variable is used as part of an
interface, e.g. as a constant in a header, then a programmer
might change its type while only intending to change its
value, leading to a more radical API change than intended.</p>
</CONS>
<DECISION>
<p><code>auto</code> is permitted, for local variables only.
Do not use <code>auto</code> for file-scope or namespace-scope
variables, or for class members.</p>
<p>The <code>auto</code> keyword is also used in an unrelated
C++11 feature: it's part of the syntax for a new kind of
function declaration with a trailing return type. Function
declarations with trailing return types are not permitted.</p>
</DECISION>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Boost"> <STYLEPOINT title="Boost">
<SUMMARY> <SUMMARY>
Use only approved libraries from the Boost library collection. Use only approved libraries from the Boost library collection.
@ -2615,11 +2760,15 @@ Tashana Landray
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="C++11"> <STYLEPOINT title="C++11">
<SUMMARY> <SUMMARY>
Use only approved libraries and language extensions from C++11 (formerly Use only approved libraries and language extensions from C++11 (formerly
known as C++0x). known as C++0x).
Currently, none are approved.
Consider portability to other environments before
using C++11 features in your project.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<DEFINITION> <DEFINITION>
@ -2639,7 +2788,7 @@ Tashana Landray
<p> <p>
The C++11 standard is substantially 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 unfamiliar 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
predict when its various features will be implemented uniformly by predict when its various features will be implemented uniformly by
tools that may be of interest (gcc, icc, clang, Eclipse, etc.). tools that may be of interest (gcc, icc, clang, Eclipse, etc.).
@ -2656,8 +2805,33 @@ Tashana Landray
</CONS> </CONS>
<DECISION> <DECISION>
Use only C++11 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.
Features will be approved individually as appropriate. Currently only the following C++11 features are approved:
<ul>
<li><code>auto</code> (for local variables only).</li>
<li>Use of <code>&gt;&gt;</code> with no intervening space to
close multiple levels of template arguments, as in
<code>set&lt;list&lt;string&gt;&gt;</code>,
where C++03 required a space as in
<code>set&lt;list&lt;string&gt; &gt;</code>.
</li>
<li>Range-based
<code>for</code> loops.</li>
<li>Use of the <code>LL</code> and <code>ULL</code> suffixes on
numeric literals to guarantee that their type is at least 64 bits
wide.</li>
<li>Variadic macros (but note
that use of macros is discouraged).</li>
<li>All of the new STL algorithms in the
<a href="http://en.cppreference.com/w/cpp/algorithm">&lt;algorithm&gt;</a>
and <a href="http://en.cppreference.com/w/cpp/numeric">&lt;numeric&gt;</a>
headers, except for the versions of
<code>min</code>, <code>max</code>, and <code>minmax</code>
whose signatures contain initializer lists.</li>
<li>Use of local types as template parameters.</li>
<li><code>nullptr</code> and <code>nullptr_t</code>.</li>
</ul>
Other features will be approved individually as appropriate.
Avoid writing code that is incompatible with C++11 (even though it Avoid writing code that is incompatible with C++11 (even though it
works in C++03). works in C++03).
@ -3097,8 +3271,6 @@ Tashana Landray
one may be you! one may be you!
</p> </p>
<STYLEPOINT title="Comment Style"> <STYLEPOINT title="Comment Style">
<SUMMARY> <SUMMARY>
Use either the <code>//</code> or <code>/* */</code> syntax, as long Use either the <code>//</code> or <code>/* */</code> syntax, as long
@ -3115,40 +3287,26 @@ Tashana Landray
<STYLEPOINT title="File Comments"> <STYLEPOINT title="File Comments">
<SUMMARY> <SUMMARY>
Start each file with a copyright notice, followed by a Start each file with license boilerplate,
description of the contents of the file. followed by a description of its contents.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<SUBSECTION title="Legal Notice and Author Line"> <SUBSECTION title="Legal Notice and Author Line">
<p> <p>
Every file should contain the following items, in order: Every file should contain license boilerplate.
<ul> Choose the appropriate boilerplate for the license used by the project
<li>a copyright statement (for example, (for example, Apache 2.0, BSD, LGPL, GPL).
<code>Copyright 2008 Google Inc.</code>)</li>
<li>a license boilerplate. Choose the appropriate boilerplate
for the license used by the project (for example,
Apache 2.0, BSD, LGPL, GPL)</li>
<li>an author line to identify the original author of the
file</li>
</ul>
</p> </p>
<p> <p>
If you make significant changes to a file that someone else If you make significant changes to a file with an author line,
originally wrote, add yourself to the author line. This can consider deleting the author line.
be very helpful when another
contributor
has questions about the file and needs to know whom to contact
about it.
</p> </p>
</SUBSECTION> </SUBSECTION>
<SUBSECTION title="File Contents"> <SUBSECTION title="File Contents">
<p> <p>
Every file should have a comment at the top, below the copyright Every file should have a comment at the top describing its contents.
notice and author line, that describes the contents of the file.
</p> </p>
<p> <p>
Generally a <code>.h</code> file will describe the classes Generally a <code>.h</code> file will describe the classes
@ -3234,7 +3392,7 @@ Tashana Landray
<li> If the function allocates memory that the caller <li> If the function allocates memory that the caller
must free. must free.
</li> </li>
<li> Whether any of the arguments can be <code>NULL</code>. <li> Whether any of the arguments can be a null pointer.
</li> </li>
<li> If there are any performance implications of how a <li> If there are any performance implications of how a
function is used. function is used.
@ -3318,7 +3476,7 @@ Tashana Landray
Each class data member (also called an instance variable or Each class data member (also called an instance variable or
member variable) should have a comment describing what it is member variable) should have a comment describing what it is
used for. If the variable can take sentinel values with used for. If the variable can take sentinel values with
special meanings, such as <code>NULL</code> or -1, document this. special meanings, such as a null pointer or -1, document this.
For example: For example:
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
@ -3396,9 +3554,9 @@ Tashana Landray
} }
</CODE_SNIPPET> </CODE_SNIPPET>
</SUBSECTION> </SUBSECTION>
<SUBSECTION title="NULL, true/false, 1, 2, 3..."> <SUBSECTION title="nullptr/NULL, true/false, 1, 2, 3...">
<p> <p>
When you pass in <code>NULL</code>, boolean, or literal integer When you pass in a null pointer, boolean, or literal integer
values to functions, you should consider adding a comment about values to functions, you should consider adding a comment about
what they are, or make your code self-documenting by using what they are, or make your code self-documenting by using
constants. For example, compare: constants. For example, compare:
@ -3455,13 +3613,11 @@ Tashana Landray
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Comments should usually be written as complete Comments should be as readable as narrative text, with proper
sentences with proper capitalization and periods at the end. capitalization and punctuation. In many cases, complete sentences are
Shorter comments, such as comments at the end of a line of more readable than sentence fragments. Shorter comments, such as
code, can sometimes be less formal, but you should be comments at the end of a line of code, can sometimes be less formal, but
consistent with your style. Complete sentences are more you should be consistent with your style.
readable, and they provide some assurance that the comment is
complete and not an unfinished thought.
</p> </p>
<p> <p>
Although it can be frustrating to have a code reviewer point Although it can be frustrating to have a code reviewer point
@ -3739,23 +3895,6 @@ Tashana Landray
<li> Wrapped parameters have a 4 space indent. <li> Wrapped parameters have a 4 space indent.
</li> </li>
</ul> </ul>
<p>
If your function is <code>const</code>, the <code>const</code>
keyword should be on the same line as the last parameter:
</p>
<CODE_SNIPPET>
// Everything in this function signature fits on a single line
ReturnType FunctionName(Type par) const {
...
}
// This function signature requires multiple lines, but
// the const keyword is on the line with the last parameter.
ReturnType ReallyLongFunctionName(Type par1,
Type par2) const {
...
}
</CODE_SNIPPET>
<p> <p>
If some parameters are unused, comment out the variable name in the If some parameters are unused, comment out the variable name in the
function definition: function definition:
@ -4349,6 +4488,9 @@ Tashana Landray
for ( ; i &lt; 5 ; ++i) { // For loops always have a space after the for ( ; i &lt; 5 ; ++i) { // For loops always have a space after the
... // semicolon, and may have a space before the ... // semicolon, and may have a space before the
// semicolon. // semicolon.
for (auto x : counts) { // Range-based for loops always have a
... // space before and after the colon.
}
switch (i) { switch (i) {
case 1: // No space before colon in a switch case. case 1: // No space before colon in a switch case.
... ...
@ -4375,7 +4517,8 @@ Tashana Landray
// &lt;, or between &gt;( in a cast. // &lt;, or between &gt;( in a cast.
vector&lt;char *&gt; x; // Spaces between type and pointer are vector&lt;char *&gt; x; // Spaces between type and pointer are
// okay, but be consistent. // okay, but be consistent.
set&lt;list&lt;string&gt; &gt; x; // C++ requires a space in &gt; &gt;. set&lt;list&lt;string&gt;&gt; x; // Permitted in C++11 code.
set&lt;list&lt;string&gt; &gt; x; // C++03 required a space in &gt; &gt;.
set&lt; list&lt;string&gt; &gt; x; // You may optionally use set&lt; list&lt;string&gt; &gt; x; // You may optionally use
// symmetric spacing in &lt; &lt;. // symmetric spacing in &lt; &lt;.
</CODE_SNIPPET> </CODE_SNIPPET>
@ -4565,7 +4708,7 @@ Tashana Landray
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 3.199 Revision 3.231
</p> </p>

91
htmlcssguide.xml
View File

@ -3,7 +3,7 @@
<GUIDE title="Google HTML/CSS Style Guide"> <GUIDE title="Google HTML/CSS Style Guide">
<p class="revision"> <p class="revision">
Revision 2.2 Revision 2.19
</p> </p>
<OVERVIEW> <OVERVIEW>
@ -13,12 +13,12 @@
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
see here on your left. Click it now. see here on your left. Click it now.
You should see “Hooray” appear below. You should see &#8220;Hooray&#8221; appear below.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Hooray! Now you know you can expand points to get more Hooray! Now you know you can expand points to get more
details. Alternatively, there’s a “toggle all” at the details. Alternatively, there&#8217;s a &#8220;toggle all&#8221; at the
top of this document. top of this document.
</p> </p>
</BODY> </BODY>
@ -52,8 +52,8 @@
files are not available over both protocols. files are not available over both protocols.
</p> </p>
<p> <p>
Omitting the protocol—which makes the URL Omitting the protocol&#8212;which makes the URL
relative—prevents mixed content issues and results in relative&#8212;prevents mixed content issues and results in
minor file size savings. minor file size savings.
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
@ -88,7 +88,7 @@
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Don’t use tabs or mix tabs and spaces for indentation. Don&#8217;t use tabs or mix tabs and spaces for indentation.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
&lt;ul&gt; &lt;ul&gt;
@ -162,8 +162,8 @@
</p> </p>
<p> <p>
(More on encodings and when and how to specify them can be (More on encodings and when and how to specify them can be
found in <a href="http://www.w3.org/International/tutorials/tutorial-char-enc/en/all.html">Character found in <a href="http://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
Sets &amp; Encodings in XHTML, HTML and CSS</a>.) character encodings in HTML and CSS</a>.)
</p> </p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -181,7 +181,7 @@
(This item is optional as it is not deemed a realistic (This item is optional as it is not deemed a realistic
expectation to always demand fully documented code. Mileage expectation to always demand fully documented code. Mileage
may vary heavily for HTML and CSS code and depends on the may vary heavily for HTML and CSS code and depends on the
project’s complexity.) project&#8217;s complexity.)
</p> </p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -230,7 +230,7 @@
<code>&lt;!DOCTYPE html&gt;</code>. <code>&lt;!DOCTYPE html&gt;</code>.
</p> </p>
<p> <p>
(It’s recommended to use HTML, as <code>text/html</code>. Do not use (It&#8217;s recommended to use HTML, as <code>text/html</code>. Do not use
XHTML. XHTML, as <a href="http://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, XHTML. XHTML, as <a href="http://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>,
lacks both browser and infrastructure support and offers lacks both browser and infrastructure support and offers
less room for optimization than HTML.) less room for optimization than HTML.)
@ -252,7 +252,8 @@
</p> </p>
<p> <p>
Use tools such as the <a href="http://validator.w3.org/nu/">W3C Use tools such as the
<a href="http://validator.w3.org/nu/">W3C
HTML validator</a> to test. HTML validator</a> to test.
</p> </p>
<p> <p>
@ -280,7 +281,7 @@
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Use elements (sometimes incorrectly called “tags”) for what Use elements (sometimes incorrectly called &#8220;tags&#8221;) for what
they have been created for. For example, use heading they have been created for. For example, use heading
elements for headings, <code>p</code> elements for elements for headings, <code>p</code> elements for
paragraphs, <code>a</code> elements for anchors, etc. paragraphs, <code>a</code> elements for anchors, etc.
@ -373,9 +374,9 @@
&lt;link rel="stylesheet" href="grid.css" media="screen"&gt; &lt;link rel="stylesheet" href="grid.css" media="screen"&gt;
&lt;link rel="stylesheet" href="print.css" media="print"&gt; &lt;link rel="stylesheet" href="print.css" media="print"&gt;
&lt;h1 style="font-size: 1em;"&gt;HTML sucks&lt;/h1&gt; &lt;h1 style="font-size: 1em;"&gt;HTML sucks&lt;/h1&gt;
&lt;p&gt;I’ve read about this on a few sites but now I’m sure: &lt;p&gt;I&#8217;ve read about this on a few sites but now I&#8217;m sure:
&lt;u&gt;HTML is stupid!!1&lt;/u&gt; &lt;u&gt;HTML is stupid!!1&lt;/u&gt;
&lt;center&gt;I can’t believe there’s no way to control the styling of &lt;center&gt;I can&#8217;t believe there&#8217;s no way to control the styling of
my website without doing everything all over again!&lt;/center&gt; my website without doing everything all over again!&lt;/center&gt;
</BAD_CODE_SNIPPET> </BAD_CODE_SNIPPET>
<CODE_SNIPPET> <CODE_SNIPPET>
@ -384,10 +385,10 @@
&lt;title&gt;My first CSS-only redesign&lt;/title&gt; &lt;title&gt;My first CSS-only redesign&lt;/title&gt;
&lt;link rel="stylesheet" href="default.css"&gt; &lt;link rel="stylesheet" href="default.css"&gt;
&lt;h1&gt;My first CSS-only redesign&lt;/h1&gt; &lt;h1&gt;My first CSS-only redesign&lt;/h1&gt;
&lt;p&gt;I’ve read about this on a few sites but today I’m actually &lt;p&gt;I&#8217;ve read about this on a few sites but today I&#8217;m actually
doing it: separating concerns and avoiding anything in the HTML of doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational. my website that is presentational.
&lt;p&gt;It’s awesome! &lt;p&gt;It&#8217;s awesome!
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -406,7 +407,7 @@
<p> <p>
The only exceptions apply to characters with special meaning The only exceptions apply to characters with special meaning
in HTML (like <code>&lt;</code> and <code>&amp;</code>) as in HTML (like <code>&lt;</code> and <code>&amp;</code>) as
well as control or “invisible” characters (like no-break well as control or &#8220;invisible&#8221; characters (like no-break
spaces). spaces).
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
@ -415,7 +416,7 @@
</BAD_CODE_SNIPPET> </BAD_CODE_SNIPPET>
<CODE_SNIPPET> <CODE_SNIPPET>
&lt;!-- Recommended --&gt; &lt;!-- Recommended --&gt;
The currency symbol for the Euro is “€”. The currency symbol for the Euro is &#8220;&#8364;&#8221;.
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -432,9 +433,9 @@
</p> </p>
<p> <p>
(This approach may require a grace period to be established (This approach may require a grace period to be established
as a wider guideline as it’s significantly different as a wider guideline as it&#8217;s significantly different
from what web developers are typically taught. For from what web developers are typically taught. For
consistency and simplicity reasons it’s best served consistency and simplicity reasons it&#8217;s best served
omitting all optional tags, not just a selection.) omitting all optional tags, not just a selection.)
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
@ -516,7 +517,7 @@
</p> </p>
<p> <p>
(If you run into issues around whitespace between list items (If you run into issues around whitespace between list items
it’s acceptable to put all <code>li</code> elements in one it&#8217;s acceptable to put all <code>li</code> elements in one
line. A linter is encouraged to throw a warning instead of line. A linter is encouraged to throw a warning instead of
an error.) an error.)
</p> </p>
@ -548,12 +549,12 @@
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="HTML quotation marks"> <STYLEPOINT title="HTML quotation marks">
<SUMMARY> <SUMMARY>
Use double quotation marks for attribute values where necessary. When quoting attributes values, use double quotation marks.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
When quoting attribute values, use double (<code>""</code>) rather Use double (<code>""</code>) rather than single quotation marks
than single quotation marks (<code>''</code>). (<code>''</code>) around attribute values.
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt; &lt;!-- Not recommended --&gt;
@ -580,8 +581,8 @@
<p> <p>
Use tools such as the Use tools such as the
<a href="http://jigsaw.w3.org/css-validator/">W3C CSS validator</a> to <a href="http://jigsaw.w3.org/css-validator/">W3C
test. CSS validator</a> to test.
</p> </p>
<p> <p>
Using valid CSS is a measurable baseline quality attribute Using valid CSS is a measurable baseline quality attribute
@ -608,7 +609,7 @@
<p> <p>
Generic names are simply a fallback for elements that have no Generic names are simply a fallback for elements that have no
particular or no meaning different from their siblings. They are particular or no meaning different from their siblings. They are
typically needed as “helpers.” typically needed as &#8220;helpers.&#8221;
</p> </p>
<p> <p>
Using functional or generic names reduces the probability of Using functional or generic names reduces the probability of
@ -723,7 +724,7 @@
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="0 and units"> <STYLEPOINT title="0 and units">
<SUMMARY> <SUMMARY>
Omit unit specification after “0” values. Omit unit specification after &#8220;0&#8221; values.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -738,7 +739,7 @@
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Leading 0s"> <STYLEPOINT title="Leading 0s">
<SUMMARY> <SUMMARY>
Omit leading “0”s in values. Omit leading &#8220;0&#8221;s in values.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -804,7 +805,7 @@
in order to improve understanding and scannability. in order to improve understanding and scannability.
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
/* Not recommended: does not separate the words “demo” and “image” */ /* Not recommended: does not separate the words &#8220;demo&#8221; and &#8220;image&#8221; */
.demoimage {} .demoimage {}
/* Not recommended: uses underscore instead of hyphen */ /* Not recommended: uses underscore instead of hyphen */
@ -819,12 +820,12 @@
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Hacks"> <STYLEPOINT title="Hacks">
<SUMMARY> <SUMMARY>
Avoid user agent detection as well as CSS “hacks”—try a different Avoid user agent detection as well as CSS &#8220;hacks&#8221;&#8212;try a different
approach first. approach first.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
It’s tempting to address styling differences over user It&#8217;s tempting to address styling differences over user
agent detection or special CSS filters, workarounds, and agent detection or special CSS filters, workarounds, and
hacks. Both approaches should be considered last resort in hacks. Both approaches should be considered last resort in
order to achieve and maintain an efficient and manageable order to achieve and maintain an efficient and manageable
@ -832,7 +833,7 @@
free pass will hurt projects in the long run as projects free pass will hurt projects in the long run as projects
tend to take the way of least resistance. That is, allowing tend to take the way of least resistance. That is, allowing
and making it easy to use detection and hacks means using and making it easy to use detection and hacks means using
detection and hacks more frequently—and more frequently detection and hacks more frequently&#8212;and more frequently
is too frequently. is too frequently.
</p> </p>
@ -918,7 +919,7 @@
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Property name stops"> <STYLEPOINT title="Property name stops">
<SUMMARY> <SUMMARY>
Use a space after a property name’s colon. Use a space after a property name&#8217;s colon.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -986,14 +987,18 @@
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="CSS quotation marks"> <STYLEPOINT title="CSS quotation marks">
<SUMMARY> <SUMMARY>
Use single quotation marks for attribute selectors and property values Use single quotation marks for attribute selectors and property values.
where necessary.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
When quoting attribute selectors and property values, use single Use single (<code>''</code>) rather than double (<code>""</code>)
(<code>''</code>) rather than double (<code>""</code>) quotation quotation marks for attribute selectors or property values. Do not
marks. Do not use quotation marks in URI values (<code>url()</code>). use quotation marks in URI values (<code>url()</code>).
</p>
<p>
Exception: If you do need to use the <code>@charset</code> rule,
use double quotation marks&#8212;<a href="http://www.w3.org/TR/CSS21/syndata.html#charset">single
quotation marks are not permitted</a>.
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
/* Not recommended */ /* Not recommended */
@ -1048,7 +1053,7 @@
<em>Be consistent.</em> <em>Be consistent.</em>
</p> </p>
<p> <p>
If you’re editing code, take a few minutes to look at the code If you&#8217;re editing code, take a few minutes to look at the code
around you and determine its style. If they use spaces around around you and determine its style. If they use spaces around
all their arithmetic operators, you should too. If their all their arithmetic operators, you should too. If their
comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them, make your
@ -1056,8 +1061,8 @@
</p> </p>
<p> <p>
The point of having style guidelines is to have a common vocabulary The point of having style guidelines is to have a common vocabulary
of coding so people can concentrate on what you’re saying rather of coding so people can concentrate on what you&#8217;re saying rather
than on how you’re saying it. We present global style rules here so than on how you&#8217;re saying it. We present global style rules here so
people know the vocabulary, but local style is also important. If people know the vocabulary, but local style is also important. If
code you add to a file looks drastically different from the existing code you add to a file looks drastically different from the existing
code around it, it throws readers out of their rhythm when they go to code around it, it throws readers out of their rhythm when they go to
@ -1066,7 +1071,7 @@
</PARTING_WORDS> </PARTING_WORDS>
<p align="right"> <p align="right">
Revision 2.2 Revision 2.19
</p> </p>
</GUIDE> </GUIDE>

715
javascriptguide.xml
View File

File diff suppressed because it is too large Load Diff

432
objcguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 2.36 Revision 2.48
</p> </p>
@ -129,13 +129,6 @@ Revision 2.36
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
// Foo.h
// AwesomeProject
//
// Created by Greg Miller on 6/13/08.
// Copyright 2008 Google, Inc. All rights reserved.
//
#import &lt;Foundation/Foundation.h&gt; #import &lt;Foundation/Foundation.h&gt;
// A sample class demonstrating good Objective-C style. All interfaces, // A sample class demonstrating good Objective-C style. All interfaces,
@ -146,8 +139,8 @@ Revision 2.36
// (no blank line between this comment and the interface) // (no blank line between this comment and the interface)
@interface Foo : NSObject { @interface Foo : NSObject {
@private @private
NSString *bar_; NSString *_bar;
NSString *bam_; NSString *_bam;
} }
// Returns an autoreleased instance of Foo. See -initWithBar: for details // Returns an autoreleased instance of Foo. See -initWithBar: for details
@ -158,7 +151,7 @@ Revision 2.36
// does a thing. // does a thing.
- (id)initWithBar:(NSString *)bar; - (id)initWithBar:(NSString *)bar;
// Gets and sets |bar_|. // Gets and sets |_bar|.
- (NSString *)bar; - (NSString *)bar;
- (void)setBar:(NSString *)bar; - (void)setBar:(NSString *)bar;
@ -177,14 +170,6 @@ Revision 2.36
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
//
// Foo.m
// AwesomeProject
//
// Created by Greg Miller on 6/13/08.
// Copyright 2008 Google, Inc. All rights reserved.
//
#import "Foo.h" #import "Foo.h"
@ -201,25 +186,25 @@ Revision 2.36
- (id)initWithBar:(NSString *)bar { - (id)initWithBar:(NSString *)bar {
if ((self = [super init])) { if ((self = [super init])) {
bar_ = [bar copy]; _bar = [bar copy];
bam_ = [[NSString alloc] initWithFormat:@"hi %d", 3]; _bam = [[NSString alloc] initWithFormat:@"hi %d", 3];
} }
return self; return self;
} }
- (void)dealloc { - (void)dealloc {
[bar_ release]; [_bar release];
[bam_ release]; [_bam release];
[super dealloc]; [super dealloc];
} }
- (NSString *)bar { - (NSString *)bar {
return bar_; return _bar;
} }
- (void)setBar:(NSString *)bar { - (void)setBar:(NSString *)bar {
[bar_ autorelease]; [_bar autorelease];
bar_ = [bar copy]; _bar = [bar copy];
} }
- (BOOL)doWorkWithBlah:(NSString *)blah { - (BOOL)doWorkWithBlah:(NSString *)blah {
@ -321,13 +306,13 @@ Revision 2.36
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
When the first keyword is shorter than the others, indent the later When the first keyword is shorter than the others, indent the later
lines by at least four spaces. You can do this by making keywords lines by at least four spaces, maintaining colon alignment:
line up vertically, not aligning colons:
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
- (void)short:(GTMFoo *)theFoo - (void)short:(GTMFoo *)theFoo
longKeyword:(NSRect)theRect longKeyword:(NSRect)theRect
evenLongerKeyword:(float)theInterval { evenLongerKeyword:(float)theInterval
error:(NSError **)theError {
... ...
} }
</CODE_SNIPPET> </CODE_SNIPPET>
@ -371,15 +356,15 @@ Revision 2.36
</BAD_CODE_SNIPPET> </BAD_CODE_SNIPPET>
<p> <p>
As with declarations and definitions, when the keyword lengths make As with declarations and definitions, when the first keyword is shorter
it impossible to align colons and still have four leading than the others, indent the later lines by at least four spaces,
spaces, indent later lines by four spaces and align keywords after the maintaining colon alignment:
first one, instead of aligning the colons.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
[myObj short:arg1 [myObj short:arg1
longKeyword:arg2 longKeyword:arg2
evenLongerKeyword:arg3]; evenLongerKeyword:arg3
error:arg4];
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -446,7 +431,7 @@ Revision 2.36
<CODE_SNIPPET> <CODE_SNIPPET>
@interface MyProtocoledClass : NSObject&lt;NSWindowDelegate&gt; { @interface MyProtocoledClass : NSObject&lt;NSWindowDelegate&gt; {
@private @private
id&lt;MyFancyDelegate&gt; delegate_; id&lt;MyFancyDelegate&gt; _delegate;
} }
- (void)setDelegate:(id&lt;MyFancyDelegate&gt;)aDelegate; - (void)setDelegate:(id&lt;MyFancyDelegate&gt;)aDelegate;
@end @end
@ -500,7 +485,7 @@ Revision 2.36
// Using a block with a C API follows the same alignment and spacing // Using a block with a C API follows the same alignment and spacing
// rules as with Objective-C. // rules as with Objective-C.
dispatch_async(fileIOQueue_, ^{ dispatch_async(_fileIOQueue, ^{
NSString* path = [self sessionFilePath]; NSString* path = [self sessionFilePath];
if (path) { if (path) {
// ... // ...
@ -535,7 +520,7 @@ Revision 2.36
void (^largeBlock)(void) = ^{ void (^largeBlock)(void) = ^{
// ... // ...
}; };
[operationQueue_ addOperationWithBlock:largeBlock]; [_operationQueue addOperationWithBlock:largeBlock];
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -579,7 +564,7 @@ Revision 2.36
<STYLEPOINT title="File Names"> <STYLEPOINT title="File Names">
<SUMMARY> <SUMMARY>
File names should reflect the name of the class implementation that File names should reflect the name of the class implementation that
they contain -- including case. Follow the convention that your they contain&#8212;including case. Follow the convention that your
project project
uses. uses.
@ -648,16 +633,16 @@ Revision 2.36
// A typical Objective-C class, using Objective-C naming. // A typical Objective-C class, using Objective-C naming.
@interface MyDelegate : NSObject { @interface MyDelegate : NSObject {
@private @private
int instanceVar_; int _instanceVar;
CrossPlatformAPI* backEndObject_; CrossPlatformAPI* _backEndObject;
} }
- (void)respondToSomething:(id)something; - (void)respondToSomething:(id)something;
@end @end
@implementation MyDelegate @implementation MyDelegate
- (void)respondToSomething:(id)something { - (void)respondToSomething:(id)something {
// bridge from Cocoa through our C++ backend // bridge from Cocoa through our C++ backend
instanceVar_ = backEndObject-&gt;DoSomethingPlatformSpecific(); _instanceVar = _backEndObject-&gt;DoSomethingPlatformSpecific();
NSString* tempString = [NSString stringWithInt:instanceVar_]; NSString* tempString = [NSString stringWithInt:_instanceVar];
NSLog(@"%@", tempString); NSLog(@"%@", tempString);
} }
@end @end
@ -752,11 +737,8 @@ Revision 2.36
<STYLEPOINT title="Variable Names"> <STYLEPOINT title="Variable Names">
<SUMMARY> <SUMMARY>
Variables names start with a lowercase and use mixed case to delimit Variables names start with a lowercase and use mixed case to delimit
words. Class member variables have trailing underscores. For example: words. Instance variables have leading underscores. For example:
<var>myLocalVariable</var>, <var>myInstanceVariable_</var>. Members <var>myLocalVariable</var>, <var>_myInstanceVariable</var>.
used for KVO/KVC bindings may begin with a leading underscore
<i>iff</i> use of Objective-C 2.0's <code>@property</code> isn't
allowed.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<SUBSECTION title="Common Variable Names"> <SUBSECTION title="Common Variable Names">
@ -786,15 +768,13 @@ Revision 2.36
<SUBSECTION title="Instance Variables"> <SUBSECTION title="Instance Variables">
<p> <p>
Instance variables are mixed case and should be suffixed with a Instance variables are mixed case and should be prefixed with an
trailing underscore, e.g. <var>usernameTextField_</var>. However, underscore e.g. <var>_usernameTextField</var>. Note that historically
we permit an exception when binding to a member variable using the convention was to put the underscore at the end of the name, and
KVO/KVC and Objective-C 2.0 cannot be used (due to OS release projects may opt to continue using trailing underscores in new code
constraints). In this case, it is acceptable to prefix the variable in order to maintain consistency within their codebase (see the
with an underscore, per Apple's accepted practices for key/value Historical Notes section). It is recommended you leave old
naming. If Objective-C 2.0 can be used, <code>@property</code> and code as-is, unless doing so would create inconsistency within a class.
<code>@synthesize</code> provide a solution that conforms to the
naming guidelines.
</p> </p>
</SUBSECTION> </SUBSECTION>
@ -825,7 +805,7 @@ Revision 2.36
When writing your comments, write for your audience: the next When writing your comments, write for your audience: the next
contributor contributor
who will need to understand your code. Be generous &#8212; the next who will need to understand your code. Be generous&#8212;the next
one may be you! one may be you!
</p> </p>
<p> <p>
@ -835,36 +815,24 @@ Revision 2.36
<STYLEPOINT title="File Comments"> <STYLEPOINT title="File Comments">
<SUMMARY> <SUMMARY>
Start each file with a basic description of the contents of the file, A file may optionally start with a description of its contents.
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">
<p>
Every file should contain the following items, in order:
<p> <ul>
Every file should contain the following items, in order: <li>license boilerplate if neccessary. Choose the appropriate
<ul> boilerplate for the license used by the project (e.g.
<li>a basic description of the contents of the file</li> Apache 2.0, BSD, LGPL, GPL).</li>
<li>an author line</li> <li>a basic description of the contents of the file if necessary.</li>
<li>a copyright statement (for example, </ul>
<code>Copyright 2008 Google Inc.</code>)</li> </p>
<li>license boilerplate if neccessary. Choose the appropriate <p>
boilerplate for the license used by the project (e.g. If you make significant changes to a file with an author line,
Apache 2.0, BSD, LGPL, GPL)</li> consider deleting the author line since revision history already
</ul> provides a more detailed and accurate record of authorship.
</p> </p>
<p>
If you make significant changes to a file that someone else
originally wrote, add yourself to the author line. This can
be very helpful when another
contributor
has questions about the file and needs to know whom to contact
about it.
</p>
</SUBSECTION>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -932,48 +900,57 @@ Revision 2.36
outside the most common Objective-C usage idioms. outside the most common Objective-C usage idioms.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <SUBSECTION title="Manual Reference Counting">
Instance variables which are pointers to objects derived from NSObject <p>
are presumed to be retained, and should be either commented as weak or Instance variables which are pointers to objects derived from NSObject
declared with the <b>__weak</b> lifetime qualifier when applicable. are presumed to be retained, and should be either commented as weak or
Similarly, declared properties must specify a <b>weak</b> or declared with the <b>__weak</b> lifetime qualifier when applicable.
<b>assign</b> property attribute if they are not retained by the Similarly, declared properties must specify an <b>assign</b> property
class. An exception is instance variables labeled as IBOutlets in Mac attribute if they are not retained by the class. An exception is
software, which are presumed to not be retained. instance variables labeled as IBOutlets in desktop Mac software,
</p> which are presumed to not be retained.
<p> </p>
Where instance variables are pointers to CoreFoundation, C++, and <p>
other non-Objective-C objects, they should always be declared with Where instance variables are pointers to Core Foundation, C++, and
the __strong and __weak type modifiers to indicate which pointers are other non-Objective-C objects, they should always be declared with
and are not retained. CoreFoundation and other non-Objective-C object the __strong or __weak type modifiers to indicate which pointers are
pointers require explicit memory management, even when building for and are not retained. Core Foundation and other non-Objective-C object
automatic reference counting or garbage collection. When the __weak pointers require explicit memory management, even when building for
type modifier is not allowed (e.g. C++ member variables when compiled automatic reference counting or garbage collection. When the __weak
under clang), a comment should be used instead. type modifier is not allowed (e.g. C++ member variables when compiled
</p> under clang), a comment should be used instead.
<p> </p>
Be mindful that support for automatic C++ objects encapsulated in <p>
Objective-C objects is disabled by default, as described <a href="http://chanson.livejournal.com/154253.html">here</a>. Be mindful that support for automatic C++ objects encapsulated in
</p> Objective-C objects is disabled by default, as described <a href="http://chanson.livejournal.com/154253.html">
<p> here</a>.
Examples of strong and weak declarations: </p>
<CODE_SNIPPET> <p>
@interface MyDelegate : NSObject { Examples of strong and weak declarations:
@private <CODE_SNIPPET>
IBOutlet NSButton *okButton_; // normal NSControl; implicitly weak on Mac only @interface MyDelegate : NSObject {
@private
IBOutlet NSButton *_okButton; // normal NSControl; implicitly weak on Mac only
AnObjcObject* doohickey_; // my doohickey AnObjcObject* _doohickey; // my doohickey
__weak MyObjcParent *parent_; // so we can send msgs back (owns me) __weak MyObjcParent *_parent; // so we can send msgs back (owns me)
// non-NSObject pointers... // non-NSObject pointers...
__strong CWackyCPPClass *wacky_; // some cross-platform object __strong CWackyCPPClass *_wacky; // some cross-platform object
__strong CFDictionaryRef *dict_; __strong CFDictionaryRef *_dict;
} }
@property(strong, nonatomic) NSString *doohickey; @property(strong, nonatomic) NSString *doohickey;
@property(weak, nonatomic) NSString *parent; @property(weak, nonatomic) NSString *parent;
@end @end
</CODE_SNIPPET> </CODE_SNIPPET>
</p> </p>
</SUBSECTION>
<SUBSECTION title="Automatic Reference Counting">
<p>
Object ownership and lifetime are explicit when using ARC, so no
additional comments are required.
</p>
</SUBSECTION>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -981,15 +958,16 @@ Revision 2.36
<CATEGORY title="Cocoa and Objective-C Features"> <CATEGORY title="Cocoa and Objective-C Features">
<STYLEPOINT title="Member Variables Should Be @private"> <STYLEPOINT title="Instance Variables In Headers Should Be @private">
<SUMMARY> <SUMMARY>
Member variables should be declared <code>@private</code>. Instance variables should be marked <code>@private</code> when they are
declared in a header file.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<CODE_SNIPPET> <CODE_SNIPPET>
@interface MyClass : NSObject { @interface MyClass : NSObject {
@private @private
id myInstanceVariable_; id _myInstanceVariable;
} }
// public accessors, setter takes ownership // public accessors, setter takes ownership
- (id)myInstanceVariable; - (id)myInstanceVariable;
@ -1083,7 +1061,7 @@ Revision 2.36
<BODY> <BODY>
<p> <p>
Unlike C++, Objective-C doesn't have a way to differentiate between Unlike C++, Objective-C doesn't have a way to differentiate between
public and private methods &#8212; everything is public. As a result, public and private methods&#8212;everything is public. As a result,
avoid placing methods in the public API unless they are actually avoid placing methods in the public API unless they are actually
expected to be used by a consumer of the class. This helps reduce the expected to be used by a consumer of the class. This helps reduce the
likelihood they'll be called when you're not expecting it. This includes likelihood they'll be called when you're not expecting it. This includes
@ -1092,7 +1070,6 @@ Revision 2.36
file as opposed to adding them to the public header. file as opposed to adding them to the public header.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
// GTMFoo.m
#import "GTMFoo.h" #import "GTMFoo.h"
@interface GTMFoo (PrivateDelegateHandling) @interface GTMFoo (PrivateDelegateHandling)
@ -1263,8 +1240,8 @@ Revision 2.36
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
- (void)setFoo:(GMFoo *)aFoo { - (void)setFoo:(GMFoo *)aFoo {
[foo_ autorelease]; // Won't dealloc if |foo_| == |aFoo| [_foo autorelease]; // Won't dealloc if |_foo| == |aFoo|
foo_ = [aFoo retain]; _foo = [aFoo retain];
} }
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
@ -1288,13 +1265,13 @@ Revision 2.36
- (id)init { - (id)init {
self = [super init]; self = [super init];
if (self) { if (self) {
bar_ = [[NSMutableString alloc] init]; // good _bar = [[NSMutableString alloc] init]; // good
} }
return self; return self;
} }
- (void)dealloc { - (void)dealloc {
[bar_ release]; // good [_bar release]; // good
[super dealloc]; [super dealloc];
} }
</CODE_SNIPPET> </CODE_SNIPPET>
@ -1352,8 +1329,8 @@ Revision 2.36
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
- (void)setFoo:(NSString *)aFoo { - (void)setFoo:(NSString *)aFoo {
[foo_ autorelease]; [_foo autorelease];
foo_ = [aFoo copy]; _foo = [aFoo copy];
} }
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
@ -1444,7 +1421,7 @@ Revision 2.36
handled by the Objective-C runtime. If the method has no return handled by the Objective-C runtime. If the method has no return
result, you're good to go. However if there is one, there may be result, you're good to go. However if there is one, there may be
differences based on runtime architecture, return size, and OS X differences based on runtime architecture, return size, and OS X
version (see <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_2_section_3.html#//apple_ref/doc/uid/TP30001163-CH11-SW7">Apple's version (see <a href="http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocObjectsClasses.html#//apple_ref/doc/uid/TP30001163-CH11-SW7">Apple's
documentation</a> for specifics). documentation</a> for specifics).
</p> </p>
<p> <p>
@ -1463,16 +1440,16 @@ Revision 2.36
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
<code>BOOL</code> is defined as an unsigned char in Objective-C which <code>BOOL</code> is defined as a signed char in Objective-C which means
means that it can have values other than <code>YES</code> (1) and that it can have values other than <code>YES</code> (1) and
<code>NO</code> (0). Do not cast or convert general integral values <code>NO</code> (0). Do not cast or convert general integral values
directly to <code>BOOL</code>. Common mistakes include casting or directly to <code>BOOL</code>. Common mistakes include casting or
converting an array's size, a pointer value, or the result of a bitwise converting an array's size, a pointer value, or the result of a bitwise
logic operation to a <code>BOOL</code> which, depending on the value of logic operation to a <code>BOOL</code> which, depending on the value of
the last byte of the integral result, could still result in a the last byte of the integral result, could still result in a
<code>NO</code> value. When converting a general integral value to a <code>NO</code> value. When converting a general integral value to a
<code>BOOL</code> use ternery operators to return a <code>YES</code> <code>BOOL</code> use ternery operators to return a <code>YES</code> or
or <code>NO</code> value. <code>NO</code> value.
</p> </p>
<p> <p>
You can safely interchange and convert <code>BOOL</code>, You can safely interchange and convert <code>BOOL</code>,
@ -1529,58 +1506,54 @@ Revision 2.36
<STYLEPOINT title="Properties"> <STYLEPOINT title="Properties">
<SUMMARY> <SUMMARY>
Properties in general are allowed with the following caveat: properties Use of the @property directive is preferred, with the following caveat:
are an Objective-C 2.0 feature which will limit your code to running properties are an Objective-C 2.0 feature which will limit your code to
on the iPhone and Mac OS X 10.5 (Leopard) and higher. Dot notation running on the iPhone and Mac OS X 10.5 (Leopard) and higher. Dot notation
is allowed only for access to a declared <code>@property</code>. is allowed only for access to a declared <code>@property</code>.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<SUBSECTION title="Naming"> <SUBSECTION title="Naming">
<p> <p>
A property's associated instance variable's name must conform to the A property's associated instance variable's name must conform to the
trailing _ requirement. The property's name should be the same as its leading _ requirement. The property's name should be the same as its
associated instance variable without the trailing _. The optional associated instance variable without the leading _. The optional space
space between the <code>@property</code> and the opening parenthesis between the <code>@property</code> and the opening parenthesis
should be omitted, as seen in the examples. should be omitted, as seen in the examples.
</p> </p>
<p>
Use the @synthesize directive to rename the property correctly.
</p>
<CODE_SNIPPET> <CODE_SNIPPET>
@interface MyClass : NSObject { @interface MyClass : NSObject
@private
NSString *name_;
}
@property(copy, nonatomic) NSString *name; @property(copy, nonatomic) NSString *name;
@end @end
@implementation MyClass @implementation MyClass
@synthesize name = name_; // No code required for auto-synthesis, else use:
// @synthesize name = _name;
@end @end
</CODE_SNIPPET> </CODE_SNIPPET>
</SUBSECTION> </SUBSECTION>
<SUBSECTION title="Location"> <SUBSECTION title="Location">
<p> <p>
A property's declaration must come immediately after the instance A property's declaration must come immediately after the instance
variable block of a class interface. A property's definition must variable block of a class interface. A property's definition (if
come immediately after the <code>@implementation</code> block in a not using automatic synthesis) must come immediately after the
class definition. They are indented at the same level as the <code>@implementation</code> block in a class definition. They are
<code>@interface</code> or <code>@implementation</code> statements indented at the same level as the <code>@interface</code> or
that they are enclosed in. <code>@implementation</code> statements that they are enclosed in.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
@interface MyClass : NSObject { @interface MyClass : NSObject {
@private @private
NSString *name_; NSString *_name;
} }
@property(copy, nonatomic) NSString *name; @property(copy, nonatomic) NSString *name;
@end @end
@implementation MyClass @implementation MyClass
@synthesize name = name_; @synthesize name = _name;
- (id)init { - (id)init {
... ...
} }
@end @end
</CODE_SNIPPET> </CODE_SNIPPET>
@ -1649,19 +1622,20 @@ Revision 2.36
<STYLEPOINT title="Automatically Synthesized Instance Variables"> <STYLEPOINT title="Automatically Synthesized Instance Variables">
<SUMMARY> <SUMMARY>
<p> <p>
For code that will run on iOS only, use of automatically synthesized Use of automatically synthesized instance variables is preferred. Code
instance variables is preferred. that must support earlier versions of the compiler toolchain (Xcode 4.3
</p> or earlier or when compiling with GCC) or is using properties inherited
<p> from a protocol should prefer the @synthesize directive.
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> </p>
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<CODE_SNIPPET> <CODE_SNIPPET>
// Header file // Header file
@interface Foo : NSObject @protocol Thingy
@property(nonatomic, copy) NSString *widgetName;
@end
@interface Foo : NSObject&lt;Thingy&gt;
// A guy walks into a bar. // A guy walks into a bar.
@property(nonatomic, copy) NSString *bar; @property(nonatomic, copy) NSString *bar;
@end @end
@ -1672,10 +1646,89 @@ Revision 2.36
@end @end
@implementation Foo @implementation Foo
@synthesize bar = bar_; @synthesize widgetName = _widgetName;
@synthesize baz = baz_;
@end @end
</CODE_SNIPPET> </CODE_SNIPPET>
<p>
Automatically synthesized instance variables take the form of the
property's name prefixed with an underscore and so typically conform to
the required variable naming style. If your property name is unusual,
or you are otherwise unable to use automatically synthesized instance
variables, use of the @synthesize directive is preferred, with the
instance variable name specified explicitly (as @synthesize does not add
a leading underscore by default).
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Automatic Reference Counting (ARC)">
<SUMMARY>
<p>
For projects that use Xcode 4.2 or later and will run only on 64-bit
Mac OS X 10.7 and iOS 5.0 and later, ARC is preferred. Use manual
reference counting when supporting earlier environments where zeroing
weak pointers are not available.
</p>
<p>
Classes that require ARC should include a preprocessor directive to
prevent compilation using manual reference counting.
</p>
<p>
Ownership qualifiers like <code>__unsafe_unretained</code> and
<code>__weak</code> should precede variable names. Specifying
<code>__strong</code> for variables is not required since it is
the default. Properties, on the other hand, should always specify the
<code>strong</code> keyword rather than relying on the compiler default.
</p>
</SUMMARY>
<BODY>
<p>
Example of an implementation file enforcing ARC style. Note that
declaring instance variables in the @implementation is permitted when
using ARC.
<CODE_SNIPPET>
#if !defined(__has_feature) || !__has_feature(objc_arc)
#error "This file requires ARC support."
#endif
#import "Foo.h"
@implementation Foo {
@private
Bar * __weak _bar;
Baz * __unsafe_unretained _baz;
}
// ...
@end
</CODE_SNIPPET>
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="NSNumber Literals">
<SUMMARY>
<p>
For projects that use Xcode 4.4 or later with clang, the use of
<a href="http://clang.llvm.org/docs/ObjectiveCLiterals.html">NSNumber literals</a>
is allowed. Note however that this will limit the portability of your
code to other toolchains.
</p>
</SUMMARY>
<BODY>
<p>
NSNumber literals are used just like Objective C string literals.
Boxing is used when necessary. Code using NSNumber literals can be
deployed on any iOS/MacOS system.
<CODE_SNIPPET>
NSNumber *fortyTwo = @42;
NSNumber *piOverTwo = @(M_PI / 2);
enum {
kMyEnum = 2;
};
NSNumber *myEnum = @(kMyEnum);
</CODE_SNIPPET>
</p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
</CATEGORY> </CATEGORY>
@ -1692,7 +1745,7 @@ Revision 2.36
A class that implements the delegate pattern should: A class that implements the delegate pattern should:
<ol> <ol>
<li> <li>
Have an instance variable named <var>delegate_</var> to reference Have an instance variable named <var>_delegate</var> to reference
the delegate. the delegate.
</li> </li>
<li> <li>
@ -1700,7 +1753,7 @@ Revision 2.36
and <code>setDelegate:</code>. and <code>setDelegate:</code>.
</li> </li>
<li> <li>
The <var>delegate_</var> object should <b>not</b> be retained. The <var>_delegate</var> object should <b>not</b> be retained.
</li> </li>
</ol> </ol>
</p> </p>
@ -1743,10 +1796,33 @@ Revision 2.36
</CATEGORY> </CATEGORY>
<CATEGORY title="Historical Notes">
<STYLEPOINT title="Trailing vs Leading Underscores">
<SUMMARY>
Trailing underscores were once preferred for instance variable names.
</SUMMARY>
<BODY>
<p>
Our style guide used to have a rule saying that instance variables
should be named with a trailing underscore, similar to the naming of
member variables in C++. This was changed to leading underscores to
be consistent with the broader Objective-C community, to better follow
Apple's official guidelines, and to allow for use of new compiler
features like automatic instance variable synthesis. New projects are
strongly encouraged to use leading underscores. Existing projects may
continue to use trailing underscores in new code to maintain
consistency with the rest of their codebase.
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 2.36 Revision 2.48
</p> </p>

25
pyguide.html
View File

@ -95,11 +95,11 @@
var matched = id && EndsWith(id, suffix); var matched = id && EndsWith(id, suffix);
if (matched) { if (matched) {
var len = id.length - suffix.length; var len = id.length - suffix.length;
ShowByName(matched.substring(0, len)); ShowByName(id.substring(0, len));
if (anchor.scrollIntoView) { if (anchor.scrollIntoView) {
anchor.scrollIntoView(); anchor.scrollIntoView();
} }
return; return;
} }
node = node.parentNode; node = node.parentNode;
@ -136,7 +136,7 @@
<H1>Google Python Style Guide</H1> <H1>Google Python Style Guide</H1>
<p align="right"> <p align="right">
Revision 2.39 Revision 2.45
</p> </p>
<address> <address>
@ -424,8 +424,9 @@ from sound.effects import echo
unless you are re-raising the exception or in the outermost unless you are re-raising the exception or in the outermost
block in your thread (and printing an error message). Python block in your thread (and printing an error message). Python
is very tolerant in this regard and <code>except:</code> will is very tolerant in this regard and <code>except:</code> will
really catch everything including Python syntax errors. It is really catch everything including misspelled names, sys.exit()
easy to hide real bugs using <code>except:</code>.</li> calls, Ctrl+C interrupts, unittest failures and all kinds of
other exceptions that you simply don't want to catch.</li>
<li>Minimize the amount of code in a <li>Minimize the amount of code in a
<code>try</code>/<code>except</code> block. The larger the <code>try</code>/<code>except</code> block. The larger the
body of the <code>try</code>, the more likely that an body of the <code>try</code>, the more likely that an
@ -988,8 +989,10 @@ from sound.effects import echo
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
of <code>apply</code>. Use list comprehensions of <code>apply</code>. Use list comprehensions
and <code>for</code> loops instead of <code>filter</code>, and <code>for</code> loops instead of <code>filter</code> and
<code>map</code>, and <code>reduce</code>. <code>map</code> when the function argument would have been an
inlined lambda anyway. Use <code>for</code> loops instead of
<code>reduce</code>.
</DIV> </DIV>
<DIV class=""><DIV class="stylepoint_body" name="Deprecated_Language_Features__body" id="Deprecated_Language_Features__body" style="display: none"> <DIV class=""><DIV class="stylepoint_body" name="Deprecated_Language_Features__body" id="Deprecated_Language_Features__body" style="display: none">
<P class=""> <P class="">
@ -1006,6 +1009,8 @@ from sound.effects import echo
<span class="external"></span>[x[1] for x in my_list if x[2] == 5] <span class="external"></span>[x[1] for x in my_list if x[2] == 5]
<span class="external"></span>map(math.sqrt, data) # Ok. No inlined lambda expression.
<span class="external"></span>fn(*args, **kwargs)</PRE></DIV> <span class="external"></span>fn(*args, **kwargs)</PRE></DIV>
<DIV class=""><PRE class="badcode">No: <span class="external"></span>words = string.split(foo, ':') <DIV class=""><PRE class="badcode">No: <span class="external"></span>words = string.split(foo, ':')
@ -1279,7 +1284,7 @@ from sound.effects import echo
<p> <p>
Make note of the indentation of the elements in the line Make note of the indentation of the elements in the line
continuation examples above; see the continuation examples above; see the
<a HREF="#indentation">indentation</a> <a HREF="#Indentation">indentation</a>
section for explanation. section for explanation.
</p> </p>
</DIV></DIV> </DIV></DIV>
@ -1458,7 +1463,7 @@ from sound.effects import echo
</A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Shebang_Line')" 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="">
Most <code>.py</code> files do not need to start with a Most <code>.py</code> files do not need to start with a
<code>#!</code> line. Start the main file of a binary with <code>#!</code> line. Start the main file of a program with
<code>#!/usr/bin/python</code>. <code>#!/usr/bin/python</code>.
</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">
@ -2218,7 +2223,7 @@ Don'<span class="external"></span>t do this.
<p align="right"> <p align="right">
Revision 2.39 Revision 2.45
</p> </p>

4
styleguide.xsl
View File

@ -119,11 +119,11 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
var matched = id &amp;&amp; EndsWith(id, suffix); var matched = id &amp;&amp; EndsWith(id, suffix);
if (matched) { if (matched) {
var len = id.length - suffix.length; var len = id.length - suffix.length;
ShowByName(matched.substring(0, len)); ShowByName(id.substring(0, len));
if (anchor.scrollIntoView) { if (anchor.scrollIntoView) {
anchor.scrollIntoView(); anchor.scrollIntoView();
} }
return; return;
} }
node = node.parentNode; node = node.parentNode;