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.245:

Browse Source 
- Relax the rule for sizeof(varname) vs. sizeof(type).
 - Allow an exception for nonconst reference parameters where
   convention dictates their use, such as for swap.
 - C++11: allow static_assert.
 - Require non-trivial fall-through between cases in switch
   statements to be annotated. Trivial fall-through includes
   consecutive case labels with no intervening code, and no comment
   is required in these cases.
 - C++11: allow constexpr.
 - Revise the "Integer Types" section to note type-width problems.
 - Clarify that the "arguments on subsequent lines" function call
   style is acceptable even when the 80-column limit doesn't require
   it.
 - Boost: allow part of Polygon.
 - C++11: allow <tuple>.

Update Objective-C style guide to 2.52:
 - Fix ARC example to not imply the use of @private in .m files.
 - Add an example to the "Category Names" section.
 - Require that ARC-using files insert preprocessor directives that
   generate an error when compiling without ARC.
 - Fix spacing around the *s in the ARC example per the C++ style
   guide.

Update Python style guide to 2.48:
 - Allow comments with URLs to exceed 80 characters per line.
 - Update outdated implicit-line-joining URLs.

Update HTML/CSS style guide to 2.21:
 - Consistent use of title case.
 - Add new "Declaration Block Separation" section.
 - Add a CSS example to the "Capitalization" section.
 - Minor fixes to whitespace.

Update JavaScript style to guide to 2.72:
 - Make it clear that the injunction against aliasing namespaces only
   applies to local aliases, not goog.scope.
 - Clarify the style guide's recommendation on array/object literals.
 - Add documentation on @private {type}, @protected {type}, and
   @const {type}.
 - Make JSDoc descriptions required only if not obvious.
 - Clarify that only private properties and methods need a trailing
   underscore.
 - Fix spelling of arv's name.

Update Common Lisp style guide to 1.18:
 - Macro-defining macros are harder to understand for everyone, not
   just for the "uninitiated." There's no need to condescend.

In all of the above style guides:
 - The guide source is now encoded as UTF-8. The numeric character
   references have been replaced with raw UTF-8-encoded characters.
This commit is contained in:
mark@chromium.org 2013-03-21 16:03:26 +00:00
parent 7cf216c976
commit 8190c132fd
6 changed files with 325 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
cppguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 3.231 Revision 3.245
</p> </p>
@ -364,7 +364,7 @@ Tashana Landray
</p> </p>
<ol> <ol>
<li> <code><var>dir2/foo2</var>.h</code> (preferred location <li> <code><var>dir2/foo2</var>.h</code> (preferred location
&#8212; see details below).</li> — see details below).</li>
<li> C system files.</li> <li> C system files.</li>
<li> C++ system files.</li> <li> C++ system files.</li>
<li> Other libraries' <code>.h</code> files.</li> <li> Other libraries' <code>.h</code> files.</li>
@ -779,6 +779,8 @@ Tashana Landray
Static or global variables of class type are forbidden: they cause Static or global variables of class type are forbidden: they cause
hard-to-find bugs due to indeterminate order of construction and hard-to-find bugs due to indeterminate order of construction and
destruction. destruction.
However, such variables are allowed if they are <code>constexpr</code>:
they have no dynamic initialization or destruction.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -1560,7 +1562,8 @@ Tashana Landray
arguments are values or <code>const</code> references while arguments are values or <code>const</code> references while
output arguments are pointers. Input parameters may be output arguments are pointers. Input parameters may be
<code>const</code> pointers, but we never allow <code>const</code> pointers, but we never allow
non-<code>const</code> reference parameters. non-<code>const</code> reference parameters
except when required by convention, e.g., <code>swap()</code>.
</p> </p>
<p> <p>
@ -2159,6 +2162,8 @@ Tashana Landray
<STYLEPOINT title="Use of const"> <STYLEPOINT title="Use of const">
<SUMMARY> <SUMMARY>
Use <code>const</code> whenever it makes sense. Use <code>const</code> whenever it makes sense.
With C++11,
<code>constexpr</code> is a better choice for some uses of const.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<DEFINITION> <DEFINITION>
@ -2243,6 +2248,51 @@ Tashana Landray
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Use of constexpr">
<SUMMARY>
In C++11, use <code>constexpr</code>
to define true constants or to ensure constant initialization.
</SUMMARY>
<BODY>
<DEFINITION>
Some variables can be declared <code>constexpr</code>
to indicate the variables are true constants,
i.e. fixed at compilation/link time.
Some functions and constructors can be declared <code>constexpr</code>
which enables them to be used
in defining a <code>constexpr</code> variable.
</DEFINITION>
<PROS>
Use of <code>constexpr</code> enables
definition of constants with floating-point expressions
rather than just literals;
definition of constants of user-defined types; and
definition of constants with function calls.
</PROS>
<CONS>
Prematurely marking something as constexpr
may cause migration problems if later on it has to be downgraded.
Current restrictions on what is allowed
in constexpr functions and constructors
may invite obscure workarounds in these definitions.
</CONS>
<DECISION>
<p>
<code>constexpr</code> definitions enable a more robust
specification of the constant parts of an interface.
Use <code>constexpr</code> to specify true constants
and the functions that support their definitions.
Avoid complexifying function definitions to enable
their use with <code>constexpr</code>.
Do not use <code>constexpr</code> to force inlining.
</p>
</DECISION>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Integer Types"> <STYLEPOINT title="Integer Types">
<SUMMARY> <SUMMARY>
Of the built-in C++ integer types, the only one used Of the built-in C++ integer types, the only one used
@ -2251,7 +2301,12 @@ Tashana Landray
size, use size, use
a precise-width integer type from a precise-width integer type from
<code>&lt;stdint.h&gt;</code>, such as <code>int16_t</code>. <code>&lt;stdint.h&gt;</code>, such as <code>int16_t</code>. If
your variable represents a value that could ever be greater than or
equal to 2^31 (2GiB), use a 64-bit type such as <code>int64_t</code>.
Keep in mind that even if your value won't ever be too large for an
<code>int</code>, it may be used in intermediate calculations which may
require a larger type. When in doubt, choose a larger type.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<DEFINITION> <DEFINITION>
@ -2301,14 +2356,24 @@ Tashana Landray
<p> <p>
You should not use the unsigned integer types such as You should not use the unsigned integer types such as
<code>uint32_t</code>, <code>uint32_t</code>,
unless the quantity you are representing is really a bit pattern unless there is a valid reason such as representing a bit pattern
rather than a number, or unless you need defined rather than a number, or you need defined overflow modulo 2^N.
twos-complement overflow. In particular, do not use unsigned In particular, do not use unsigned types to say a number will never
types to say a number will never be negative. Instead, use be negative. Instead, use
assertions for this. assertions for this.
</p> </p>
<p>
If your code is a container that returns a size, be sure to use
a type that will accommodate any possible usage of your container.
When in doubt, use a larger type rather than a smaller type.
</p>
<p>
Use care when converting integer types. Integer conversions and
promotions can cause non-intuitive behavior.
</p>
</DECISION> </DECISION>
<SUBSECTION title="On Unsigned Integers"> <SUBSECTION title="On Unsigned Integers">
@ -2571,16 +2636,21 @@ Tashana Landray
<STYLEPOINT title="sizeof"> <STYLEPOINT title="sizeof">
<SUMMARY> <SUMMARY>
Use <code>sizeof(<var>varname</var>)</code> instead of Prefer <code>sizeof(<var>varname</var>)</code> to
<code>sizeof(<var>type</var>)</code> whenever possible. <code>sizeof(<var>type</var>)</code>.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Use <code>sizeof(<var>varname</var>)</code> because it will update Use <code>sizeof(<var>varname</var>)</code>
appropriately if the type of the variable changes. when you take the size of a particular variable.
<code>sizeof(<var>type</var>)</code> may make sense in some cases, <code>sizeof(<var>varname</var>)</code> will update
but should generally be avoided because it can fall out of sync if appropriately if someone changes the variable type
the variable's type changes. either now or later.
You may use <code>sizeof(<var>type</var>)</code>
for code unrelated to any particular variable,
such as code that manages an external or internal
data format where a variable of an appropriate C++ type
is not convenient.
</p> </p>
<p> <p>
<CODE_SNIPPET> <CODE_SNIPPET>
@ -2590,6 +2660,12 @@ Tashana Landray
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
memset(&amp;data, 0, sizeof(Struct)); memset(&amp;data, 0, sizeof(Struct));
</BAD_CODE_SNIPPET> </BAD_CODE_SNIPPET>
<CODE_SNIPPET>
if (raw_size &lt; sizeof(int)) {
LOG(ERROR) &lt;&lt; "compressed record not big enough for count: " &lt;&lt; raw_size;
return false;
}
</CODE_SNIPPET>
</p> </p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -2666,7 +2742,7 @@ Tashana Landray
auto x(3); // Note: parentheses. auto x(3); // Note: parentheses.
auto y{3}; // Note: curly braces. auto y{3}; // Note: curly braces.
</CODE_SNIPPET> </CODE_SNIPPET>
mean different things &#8212; <code>x</code> is mean different things — <code>x</code> is
an <code>int</code>, while <code>y</code> is an <code>int</code>, while <code>y</code> is
an <code>initializer_list</code>. The same applies to other an <code>initializer_list</code>. The same applies to other
normally-invisible proxy types. normally-invisible proxy types.
@ -2752,6 +2828,13 @@ Tashana Landray
<code>boost/iterator/iterator_adaptor.hpp</code>, <code>boost/iterator/iterator_adaptor.hpp</code>,
<code>boost/iterator/iterator_facade.hpp</code>, and <code>boost/iterator/iterator_facade.hpp</code>, and
<code>boost/function_output_iterator.hpp</code></li> <code>boost/function_output_iterator.hpp</code></li>
<li> The part of
<a href="http://www.boost.org/libs/polygon/">
Polygon</a> that deals with Voronoi diagram construction and
doesn't depend on the rest of Polygon:
<code>boost/polygon/voronoi_builder.hpp</code>,
<code>boost/polygon/voronoi_diagram.hpp</code>, and
<code>boost/polygon/voronoi_geometry_type.hpp</code></li>
</ul> </ul>
We are actively considering adding other Boost features to the list, so We are actively considering adding other Boost features to the list, so
this rule may be relaxed in the future. this rule may be relaxed in the future.
@ -2795,7 +2878,7 @@ Tashana Landray
</p> </p>
<p> <p>
As with <a href="#Boost">Boost</a>, some C++11 extensions encourage As with <a href="#Boost">Boost</a>, some C++11 extensions encourage
coding practices that hamper readability&#8212;for example by removing coding practices that hamper readability—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
duplicate functionality available through existing duplicate functionality available through existing
@ -2809,6 +2892,8 @@ Tashana Landray
Currently only the following C++11 features are approved: Currently only the following C++11 features are approved:
<ul> <ul>
<li><code>auto</code> (for local variables only).</li> <li><code>auto</code> (for local variables only).</li>
<li>
<code>constexpr</code> (for ensuring constants).</li>
<li>Use of <code>&gt;&gt;</code> with no intervening space to <li>Use of <code>&gt;&gt;</code> with no intervening space to
close multiple levels of template arguments, as in close multiple levels of template arguments, as in
<code>set&lt;list&lt;string&gt;&gt;</code>, <code>set&lt;list&lt;string&gt;&gt;</code>,
@ -2830,6 +2915,9 @@ Tashana Landray
whose signatures contain initializer lists.</li> whose signatures contain initializer lists.</li>
<li>Use of local types as template parameters.</li> <li>Use of local types as template parameters.</li>
<li><code>nullptr</code> and <code>nullptr_t</code>.</li> <li><code>nullptr</code> and <code>nullptr_t</code>.</li>
<li><code>static_assert</code>.</li>
<li>Everything in <a href="http://en.cppreference.com/w/cpp/header/tuple">&lt;tuple&gt;</a>.
</li>
</ul> </ul>
Other features will be approved individually as appropriate. 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
@ -2995,8 +3083,8 @@ Tashana Landray
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
The names of all types &#8212; classes, structs, typedefs, and enums The names of all types — classes, structs, typedefs, and enums
&#8212; have the same naming convention. Type names should start — have the same naming convention. Type names should start
with a capital letter and have a capital letter for each new with a capital letter and have a capital letter for each new
word. No underscores. For example: word. No underscores. For example:
</p> </p>
@ -3267,7 +3355,7 @@ Tashana Landray
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 — the next
one may be you! one may be you!
</p> </p>
@ -3802,7 +3890,7 @@ Tashana Landray
an encoding understood by most tools able an encoding understood by most tools able
to handle more than just ASCII. to handle more than just ASCII.
Hex encoding is also OK, and encouraged where it enhances Hex encoding is also OK, and encouraged where it enhances
readability &#8212; for example, <code>"\xEF\xBB\xBF"</code> is the readability — for example, <code>"\xEF\xBB\xBF"</code> is the
Unicode zero-width no-break space character, which would be Unicode zero-width no-break space character, which would be
invisible if included in the source as straight UTF-8. invisible if included in the source as straight UTF-8.
</p> </p>
@ -3956,22 +4044,26 @@ Tashana Landray
argument4); argument4);
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
If the function signature is so long that it cannot fit within Arguments may optionally all be placed on subsequent lines, with one
the maximum <a href="#Line_Length">line length</a>, you may line per argument:
place all arguments on subsequent lines:
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
if (...) { if (...) {
... ...
... ...
if (...) { if (...) {
DoSomethingThatRequiresALongFunctionName( DoSomething(
very_long_argument1, // 4 space indent argument1, // 4 space indent
argument2, argument2,
argument3, argument3,
argument4); argument4);
} }
</CODE_SNIPPET> </CODE_SNIPPET>
<p>
In particular, this should be done if the function signature is so long
that it cannot fit within the maximum <a href="#Line_Length">line
length</a>.
</p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -4097,8 +4189,9 @@ Tashana Landray
<STYLEPOINT title="Loops and Switch Statements"> <STYLEPOINT title="Loops and Switch Statements">
<SUMMARY> <SUMMARY>
Switch statements may use braces for blocks. Empty loop bodies should use Switch statements may use braces for blocks. Annotate non-trivial
<code>{}</code> or <code>continue</code>. fall-through between cases. Empty loop bodies should use <code>{}</code>
or <code>continue</code>.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -4130,6 +4223,8 @@ Tashana Landray
} }
} }
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
Empty loop bodies should use <code>{}</code> or Empty loop bodies should use <code>{}</code> or
<code>continue</code>, but not a single semicolon. <code>continue</code>, but not a single semicolon.
@ -4708,7 +4803,7 @@ Tashana Landray
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 3.231 Revision 3.245
</p> </p>

178
htmlcssguide.xml
View File

@ -3,22 +3,22 @@
<GUIDE title="Google HTML/CSS Style Guide"> <GUIDE title="Google HTML/CSS Style Guide">
<p class="revision"> <p class="revision">
Revision 2.19 Revision 2.21
</p> </p>
<OVERVIEW> <OVERVIEW>
<CATEGORY title="Important Note"> <CATEGORY title="Important Note">
<STYLEPOINT title="Displaying Hidden Details in this Guide"> <STYLEPOINT title="Displaying Hidden Details in This Guide">
<SUMMARY> <SUMMARY>
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 &#8220;Hooray&#8221; appear below. You should see “Hooray” 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&#8217;s a &#8220;toggle all&#8221; at the details. Alternatively, there’s a “toggle all” 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&#8212;which makes the URL Omitting the protocol—which makes the URL
relative&#8212;prevents mixed content issues and results in relative—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&#8217;t use tabs or mix tabs and spaces for indentation. Don’t use tabs or mix tabs and spaces for indentation.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
&lt;ul&gt; &lt;ul&gt;
@ -109,9 +109,9 @@
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
All code has to be lowercase: This applies to element names, All code has to be lowercase: This applies to HTML element names,
attributes, attribute values (unless attributes, attribute values (unless
text/<code>CDATA</code>), selectors, properties, and <code>text/CDATA</code>), CSS selectors, properties, and
property values (with the exception of strings). property values (with the exception of strings).
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
@ -122,9 +122,17 @@
&lt;!-- Recommended --&gt; &lt;!-- Recommended --&gt;
&lt;img src="google.png" alt="Google"&gt; &lt;img src="google.png" alt="Google"&gt;
</CODE_SNIPPET> </CODE_SNIPPET>
<BAD_CODE_SNIPPET>
/* Not recommended */
color: #E5E5E5;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
color: #e5e5e5;
</CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Trailing whitespace"> <STYLEPOINT title="Trailing Whitespace">
<SUMMARY> <SUMMARY>
Remove trailing white spaces. Remove trailing white spaces.
</SUMMARY> </SUMMARY>
@ -181,11 +189,11 @@
(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&#8217;s complexity.) project’s complexity.)
</p> </p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Action items"> <STYLEPOINT title="Action Items">
<SUMMARY> <SUMMARY>
Mark todos and action items with <code>TODO</code>. Mark todos and action items with <code>TODO</code>.
</SUMMARY> </SUMMARY>
@ -220,7 +228,7 @@
</CATEGORY> </CATEGORY>
<CATEGORY title="HTML Style Rules"> <CATEGORY title="HTML Style Rules">
<STYLEPOINT title="Document type"> <STYLEPOINT title="Document Type">
<SUMMARY> <SUMMARY>
Use HTML5. Use HTML5.
</SUMMARY> </SUMMARY>
@ -230,7 +238,7 @@
<code>&lt;!DOCTYPE html&gt;</code>. <code>&lt;!DOCTYPE html&gt;</code>.
</p> </p>
<p> <p>
(It&#8217;s recommended to use HTML, as <code>text/html</code>. Do not use (It’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.)
@ -241,7 +249,7 @@
</p> </p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="HTML validity"> <STYLEPOINT title="HTML Validity">
<SUMMARY> <SUMMARY>
Use valid HTML where possible. Use valid HTML where possible.
</SUMMARY> </SUMMARY>
@ -252,8 +260,7 @@
</p> </p>
<p> <p>
Use tools such as the Use tools such as the <a href="http://validator.w3.org/nu/">W3C
<a href="http://validator.w3.org/nu/">W3C
HTML validator</a> to test. HTML validator</a> to test.
</p> </p>
<p> <p>
@ -281,7 +288,7 @@
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Use elements (sometimes incorrectly called &#8220;tags&#8221;) for what Use elements (sometimes incorrectly called “tags”) 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.
@ -301,7 +308,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Multimedia fallback"> <STYLEPOINT title="Multimedia Fallback">
<SUMMARY> <SUMMARY>
Provide alternative contents for multimedia. Provide alternative contents for multimedia.
</SUMMARY> </SUMMARY>
@ -338,7 +345,7 @@
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Separation of concerns"> <STYLEPOINT title="Separation of Concerns">
<SUMMARY> <SUMMARY>
Separate structure from presentation from behavior. Separate structure from presentation from behavior.
</SUMMARY> </SUMMARY>
@ -374,9 +381,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&#8217;ve read about this on a few sites but now I&#8217;m sure: &lt;p&gt;I’ve read about this on a few sites but now I’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&#8217;t believe there&#8217;s no way to control the styling of &lt;center&gt;I can’t believe there’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>
@ -385,14 +392,14 @@
&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&#8217;ve read about this on a few sites but today I&#8217;m actually &lt;p&gt;I’ve read about this on a few sites but today I’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&#8217;s awesome! &lt;p&gt;It’s awesome!
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Entity references"> <STYLEPOINT title="Entity References">
<SUMMARY> <SUMMARY>
Do not use entity references. Do not use entity references.
</SUMMARY> </SUMMARY>
@ -407,7 +414,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 &#8220;invisible&#8221; characters (like no-break well as control or “invisible” characters (like no-break
spaces). spaces).
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
@ -416,11 +423,11 @@
</BAD_CODE_SNIPPET> </BAD_CODE_SNIPPET>
<CODE_SNIPPET> <CODE_SNIPPET>
&lt;!-- Recommended --&gt; &lt;!-- Recommended --&gt;
The currency symbol for the Euro is &#8220;&#8364;&#8221;. The currency symbol for the Euro is “€”.
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Optional tags"> <STYLEPOINT title="Optional Tags">
<SUMMARY> <SUMMARY>
Omit optional tags (optional). Omit optional tags (optional).
</SUMMARY> </SUMMARY>
@ -433,9 +440,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&#8217;s significantly different as a wider guideline as it’s significantly different
from what web developers are typically taught. For from what web developers are typically taught. For
consistency and simplicity reasons it&#8217;s best served consistency and simplicity reasons it’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>
@ -458,7 +465,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="type attributes"> <STYLEPOINT title="type Attributes">
<SUMMARY> <SUMMARY>
Omit <code>type</code> attributes for style sheets and scripts. Omit <code>type</code> attributes for style sheets and scripts.
</SUMMARY> </SUMMARY>
@ -499,7 +506,7 @@
</CATEGORY> </CATEGORY>
<CATEGORY title="HTML Formatting Rules"> <CATEGORY title="HTML Formatting Rules">
<STYLEPOINT title="General formatting"> <STYLEPOINT title="General Formatting">
<SUMMARY> <SUMMARY>
Use a new line for every block, list, or table element, and Use a new line for every block, list, or table element, and
indent every such child element. indent every such child element.
@ -517,7 +524,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&#8217;s acceptable to put all <code>li</code> elements in one it’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>
@ -547,7 +554,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="HTML quotation marks"> <STYLEPOINT title="HTML Quotation Marks">
<SUMMARY> <SUMMARY>
When quoting attributes values, use double quotation marks. When quoting attributes values, use double quotation marks.
</SUMMARY> </SUMMARY>
@ -569,7 +576,7 @@
</CATEGORY> </CATEGORY>
<CATEGORY title="CSS Style Rules"> <CATEGORY title="CSS Style Rules">
<STYLEPOINT title="CSS validity"> <STYLEPOINT title="CSS Validity">
<SUMMARY> <SUMMARY>
Use valid CSS where possible. Use valid CSS where possible.
</SUMMARY> </SUMMARY>
@ -580,8 +587,7 @@
</p> </p>
<p> <p>
Use tools such as the Use tools such as the <a href="http://jigsaw.w3.org/css-validator/">W3C
<a href="http://jigsaw.w3.org/css-validator/">W3C
CSS validator</a> to test. CSS validator</a> to test.
</p> </p>
<p> <p>
@ -591,7 +597,7 @@
</p> </p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="ID and class naming"> <STYLEPOINT title="ID and Class Naming">
<SUMMARY> <SUMMARY>
Use meaningful or generic ID and class names. Use meaningful or generic ID and class names.
</SUMMARY> </SUMMARY>
@ -609,7 +615,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 &#8220;helpers.&#8221; typically needed as “helpers.”
</p> </p>
<p> <p>
Using functional or generic names reduces the probability of Using functional or generic names reduces the probability of
@ -635,7 +641,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="ID and class name style"> <STYLEPOINT title="ID and Class Name Style">
<SUMMARY> <SUMMARY>
Use ID and class names that are as short as possible but as long as Use ID and class names that are as short as possible but as long as
necessary. necessary.
@ -662,7 +668,7 @@
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Type selectors"> <STYLEPOINT title="Type Selectors">
<SUMMARY> <SUMMARY>
Avoid qualifying ID and class names with type selectors. Avoid qualifying ID and class names with type selectors.
</SUMMARY> </SUMMARY>
@ -671,8 +677,7 @@
use element names in conjunction with IDs or classes. use element names in conjunction with IDs or classes.
</p> </p>
<p> <p>
Avoiding unnecessary ancestor selectors is useful for Avoiding unnecessary ancestor selectors is useful for <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance
<a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance
reasons</a>. reasons</a>.
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
@ -687,14 +692,13 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Shorthand properties"> <STYLEPOINT title="Shorthand Properties">
<SUMMARY> <SUMMARY>
Use shorthand properties where possible. Use shorthand properties where possible.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
CSS offers a variety of CSS offers a variety of <a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
<a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
properties (like <code>font</code>) properties (like <code>font</code>)
that should be used whenever possible, even in cases where that should be used whenever possible, even in cases where
only one value is explicitly set. only one value is explicitly set.
@ -722,9 +726,9 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="0 and units"> <STYLEPOINT title="0 and Units">
<SUMMARY> <SUMMARY>
Omit unit specification after &#8220;0&#8221; values. Omit unit specification after “0” values.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -739,7 +743,7 @@
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Leading 0s"> <STYLEPOINT title="Leading 0s">
<SUMMARY> <SUMMARY>
Omit leading &#8220;0&#8221;s in values. Omit leading “0”s in values.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -751,7 +755,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Hexadecimal notation"> <STYLEPOINT title="Hexadecimal Notation">
<SUMMARY> <SUMMARY>
Use 3 character hexadecimal notation where possible. Use 3 character hexadecimal notation where possible.
</SUMMARY> </SUMMARY>
@ -794,7 +798,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="ID and class name delimiters"> <STYLEPOINT title="ID and Class Name Delimiters">
<SUMMARY> <SUMMARY>
Separate words in ID and class names by a hyphen. Separate words in ID and class names by a hyphen.
</SUMMARY> </SUMMARY>
@ -805,7 +809,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 &#8220;demo&#8221; and &#8220;image&#8221; */ /* Not recommended: does not separate the words “demo” and “image” */
.demoimage {} .demoimage {}
/* Not recommended: uses underscore instead of hyphen */ /* Not recommended: uses underscore instead of hyphen */
@ -820,12 +824,12 @@
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Hacks"> <STYLEPOINT title="Hacks">
<SUMMARY> <SUMMARY>
Avoid user agent detection as well as CSS &#8220;hacks&#8221;&#8212;try a different Avoid user agent detection as well as CSS “hacks”—try a different
approach first. approach first.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
It&#8217;s tempting to address styling differences over user It’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
@ -833,7 +837,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&#8212;and more frequently detection and hacks more frequently—and more frequently
is too frequently. is too frequently.
</p> </p>
@ -843,7 +847,7 @@
</CATEGORY> </CATEGORY>
<CATEGORY title="CSS Formatting Rules"> <CATEGORY title="CSS Formatting Rules">
<STYLEPOINT title="Declaration order"> <STYLEPOINT title="Declaration Order">
<SUMMARY> <SUMMARY>
Alphabetize declarations. Alphabetize declarations.
</SUMMARY> </SUMMARY>
@ -870,7 +874,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Block content indentation"> <STYLEPOINT title="Block Content Indentation">
<SUMMARY> <SUMMARY>
Indent all block content. Indent all block content.
</SUMMARY> </SUMMARY>
@ -892,7 +896,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Declaration stops"> <STYLEPOINT title="Declaration Stops">
<SUMMARY> <SUMMARY>
Use a semicolon after every declaration. Use a semicolon after every declaration.
</SUMMARY> </SUMMARY>
@ -917,9 +921,9 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Property name stops"> <STYLEPOINT title="Property Name Stops">
<SUMMARY> <SUMMARY>
Use a space after a property name&#8217;s colon. Use a space after a property name’s colon.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -940,7 +944,41 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Selector and declaration separation"> <STYLEPOINT title="Declaration Block Separation">
<SUMMARY>
Use a space between the last selector and the declaration block.
</SUMMARY>
<BODY>
<p>
Always use a single space between the last selector and the opening
brace that begins the <a href="http://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration
block</a>.
</p>
<p>
The opening brace should be on the same line as the last selector in a
given rule.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended: missing space */
#video{
margin-top: 1em;
}
/* Not recommended: unnecessary line break */
#video
{
margin-top: 1em;
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#video {
margin-top: 1em;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Selector and Declaration Separation">
<SUMMARY> <SUMMARY>
Separate selectors and declarations by new lines. Separate selectors and declarations by new lines.
</SUMMARY> </SUMMARY>
@ -965,13 +1003,13 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
<STYLEPOINT title="Rule separation"> <STYLEPOINT title="Rule Separation">
<SUMMARY> <SUMMARY>
Separate rules by new lines. Separate rules by new lines.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Always put a line between rules. Always put a blank line (two line breaks) between rules.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
html { html {
@ -985,7 +1023,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</BODY> </BODY>
</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.
</SUMMARY> </SUMMARY>
@ -997,7 +1035,7 @@
</p> </p>
<p> <p>
Exception: If you do need to use the <code>@charset</code> rule, 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 use double quotation marks—<a href="http://www.w3.org/TR/CSS21/syndata.html#charset">single
quotation marks are not permitted</a>. quotation marks are not permitted</a>.
</p> </p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
@ -1022,7 +1060,7 @@
<CATEGORY title="CSS Meta Rules"> <CATEGORY title="CSS Meta Rules">
<STYLEPOINT title="Section comments"> <STYLEPOINT title="Section Comments">
<SUMMARY> <SUMMARY>
Group sections by a section comment (optional). Group sections by a section comment (optional).
</SUMMARY> </SUMMARY>
@ -1053,7 +1091,7 @@
<em>Be consistent.</em> <em>Be consistent.</em>
</p> </p>
<p> <p>
If you&#8217;re editing code, take a few minutes to look at the code If you’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
@ -1061,8 +1099,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&#8217;re saying rather of coding so people can concentrate on what you’re saying rather
than on how you&#8217;re saying it. We present global style rules here so than on how you’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
@ -1071,7 +1109,7 @@
</PARTING_WORDS> </PARTING_WORDS>
<p align="right"> <p align="right">
Revision 2.19 Revision 2.21
</p> </p>
</GUIDE> </GUIDE>

50
javascriptguide.xml
View File

@ -3,14 +3,14 @@
<GUIDE title="Google JavaScript Style Guide"> <GUIDE title="Google JavaScript Style Guide">
<p class="revision"> <p class="revision">
Revision 2.64 Revision 2.72
</p> </p>
<address> <address>
Aaron Whyte<br/> Aaron Whyte<br/>
Bob Jervis<br/> Bob Jervis<br/>
Dan Pupius<br/> Dan Pupius<br/>
Eric Arvidsson<br/> Erik Arvidsson<br/>
Fritz Schneider<br/> Fritz Schneider<br/>
Robby Walker<br/> Robby Walker<br/>
</address> </address>
@ -96,7 +96,7 @@
<code>boolean</code>) are constant values.</p> <code>boolean</code>) are constant values.</p>
<p><code>Objects</code>' <p><code>Objects</code>'
immutabilty is more subjective &#8212; objects should be immutabilty is more subjective — objects should be
considered immutable only if they do not demonstrate obeserverable considered immutable only if they do not demonstrate obeserverable
state change. This is not enforced by the compiler.</p> state change. This is not enforced by the compiler.</p>
@ -729,11 +729,10 @@
<BODY> <BODY>
<SUBSECTION title="Properties and methods"> <SUBSECTION title="Properties and methods">
<ul> <ul>
<li><em>Private</em> properties, variables, and methods (in files <li><em>Private</em> properties and methods should be named with a
or classes) should be named with a trailing trailing underscore.
underscore.
</li> </li>
<li><em>Protected</em> properties, variables, and methods should be <li><em>Protected</em> properties and methods should be
named without a trailing underscore (like public ones).</li> named without a trailing underscore (like public ones).</li>
</ul> </ul>
<p>For more information on <em>private</em> and <em>protected</em>, <p>For more information on <em>private</em> and <em>protected</em>,
@ -892,7 +891,8 @@
staticHelper(new MyClass()); staticHelper(new MyClass());
}; };
</CODE_SNIPPET> </CODE_SNIPPET>
<p>Do not alias namespaces.</p> <p>Do not create local aliases of namespaces. Namespaces should only
be aliased using <a href="#goog-scope">goog.scope</a>.</p>
<BAD_CODE_SNIPPET> <BAD_CODE_SNIPPET>
myapp.main = function() { myapp.main = function() {
var namespace = some.long.namespace; var namespace = some.long.namespace;
@ -999,7 +999,7 @@
var obj = {a: 1, b: 2, c: 3}; // No space after { or before }. var obj = {a: 1, b: 2, c: 3}; // No space after { or before }.
</CODE_SNIPPET> </CODE_SNIPPET>
<p>Multiline array initializers and object initializers are indented <p>Multiline array initializers and object initializers are indented
2 spaces, just like blocks.</p> 2 spaces, with the braces on their own line, just like blocks.</p>
<CODE_SNIPPET> <CODE_SNIPPET>
// Object initializer. // Object initializer.
var inset = { var inset = {
@ -1127,6 +1127,7 @@
</CODE_SNIPPET> </CODE_SNIPPET>
</SUBSECTION> </SUBSECTION>
<SUBSECTION title="Aliasing with goog.scope"> <SUBSECTION title="Aliasing with goog.scope">
<a name="goog-scope"/>
<p> <p>
<a href="https://docs.google.com/document/pub?id=1ETFAuh2kaXMVL-vafUYhaWlhl6b5D9TOvboVg7Zl68Y"><code>goog.scope</code></a> <a href="https://docs.google.com/document/pub?id=1ETFAuh2kaXMVL-vafUYhaWlhl6b5D9TOvboVg7Zl68Y"><code>goog.scope</code></a>
may be used to shorten references to may be used to shorten references to
@ -2204,7 +2205,10 @@
<p>All files, classes, methods and properties should be documented with <p>All files, classes, methods and properties should be documented with
<a href="http://code.google.com/p/jsdoc-toolkit/">JSDoc</a> <a href="http://code.google.com/p/jsdoc-toolkit/">JSDoc</a>
comments with the appropriate <a href="#JSDoc_Tag_Reference">tags</a> comments with the appropriate <a href="#JSDoc_Tag_Reference">tags</a>
and <a href="#JsTypes">types</a>.</p> and <a href="#JsTypes">types</a>. Textual descriptions for methods,
method parameters and method return values should be included
unless obvious from the method or parameter name.
</p>
<p>Inline comments should be of the <code>//</code> variety.</p> <p>Inline comments should be of the <code>//</code> variety.</p>
@ -2438,15 +2442,15 @@
<tr> <tr>
<td><a name="tag-const">@const</a></td> <td><a name="tag-const">@const</a></td>
<td> <td>
<code>@const</code> <code>@const</code><br/>
<code>@const {type}</code>
<p><i>For example:</i></p> <p><i>For example:</i></p>
<CODE_SNIPPET> <CODE_SNIPPET>
/** @const */ var MY_BEER = 'stout'; /** @const */ var MY_BEER = 'stout';
/** /**
* My namespace's favorite kind of beer. * My namespace's favorite kind of beer.
* @const * @const {string}
* @type {string}
*/ */
mynamespace.MY_BEER = 'stout'; mynamespace.MY_BEER = 'stout';
@ -2476,7 +2480,7 @@
<p>When <code>@const</code> is applied to a method, it <p>When <code>@const</code> is applied to a method, it
implies the method is not only not overwritable, but also implies the method is not only not overwritable, but also
that the method is <em>finalized</em> &#8212; that the method is <em>finalized</em> —
not overridable in subclasses.</p> not overridable in subclasses.</p>
<p>For more on <code>@const</code>, see the <p>For more on <code>@const</code>, see the
@ -2861,6 +2865,10 @@
</td> </td>
</tr> </tr>
<tr> <tr>
<td><a name="tag-noalias">@noalias</a></td> <td><a name="tag-noalias">@noalias</a></td>
<td> <td>
@ -2962,13 +2970,13 @@
<tr> <tr>
<td><a name="tag-private">@private</a></td> <td><a name="tag-private">@private</a></td>
<td> <td>
<code>@private</code> <code>@private</code><br/>
<code>@private {type}</code>
<p><i>For example:</i></p> <p><i>For example:</i></p>
<CODE_SNIPPET> <CODE_SNIPPET>
/** /**
* Handlers that are listening to this logger. * Handlers that are listening to this logger.
* @type Array.&lt;Function&gt; * @private {!Array.&lt;Function&gt;}
* @private
*/ */
this.handlers_ = []; this.handlers_ = [];
</CODE_SNIPPET> </CODE_SNIPPET>
@ -2985,7 +2993,8 @@
<tr> <tr>
<td><a name="tag-protected">@protected</a></td> <td><a name="tag-protected">@protected</a></td>
<td> <td>
<code>@protected</code> <code>@protected</code><br/>
<code>@protected {type}</code>
<p><i>For example:</i></p> <p><i>For example:</i></p>
<CODE_SNIPPET> <CODE_SNIPPET>
/** /**
@ -3222,6 +3231,9 @@
<a href="#Typedefs">complex type</a>. <a href="#Typedefs">complex type</a>.
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
@ -3527,7 +3539,7 @@
</PARTING_WORDS> </PARTING_WORDS>
<p align="right"> <p align="right">
Revision 2.64 Revision 2.72
</p> </p>

38
lispguide.xml
View File

@ -5,7 +5,7 @@
<p align="right"> <p align="right">
Revision 1.17 Revision 1.18
</p> </p>
@ -13,7 +13,7 @@ Revision 1.17
Robert Brown Robert Brown
</address> </address>
<address> <address>
<a HREF="mailto:tunes@google.com">Fran&#231;ois-Ren&#233; Rideau</a> <a HREF="mailto:tunes@google.com">François-René Rideau</a>
</address> </address>
<address> <address>
@ -21,7 +21,7 @@ Robert Brown
</address> </address>
<p align="center"> <p align="center">
<cite>Patterns mean "I have run out of language."</cite> &#8212; Rich Hickey <cite>Patterns mean "I have run out of language."</cite> — Rich Hickey
</p> </p>
@ -305,7 +305,7 @@ Robert Brown
<li> <li>
Every developer's code must be easy for another developer Every developer's code must be easy for another developer
to read, understand, and modify to read, understand, and modify
&#8212; even if the first developer isn't around to explain it. — even if the first developer isn't around to explain it.
(This is the "hit by a truck" principle.) (This is the "hit by a truck" principle.)
</li> </li>
<li> <li>
@ -314,7 +314,7 @@ Robert Brown
and recognize it as "Fred's code" by its style. and recognize it as "Fred's code" by its style.
</li> </li>
<li> <li>
Don't be "clever" &#8212; Don't be "clever" —
do the simplest thing that could possibly work properly. do the simplest thing that could possibly work properly.
</li> </li>
<li> <li>
@ -324,7 +324,7 @@ Robert Brown
Be concise. Be concise.
</li> </li>
<li> <li>
KISS &#8212; Keep It Simple, Stupid. KISS — Keep It Simple, Stupid.
</li> </li>
<li> <li>
Use the smallest hammer for the job. Use the smallest hammer for the job.
@ -411,7 +411,7 @@ Robert Brown
(including QA or Ops), or otherwise isn't purely local, (including QA or Ops), or otherwise isn't purely local,
you must write it up using at least a couple of paragraphs, you must write it up using at least a couple of paragraphs,
and get a design approval from the other parties involved and get a design approval from the other parties involved
before starting to write code &#8212; or be ready to scratch what you have before starting to write code — or be ready to scratch what you have
when they object. when they object.
</p> </p>
<p> <p>
@ -1344,7 +1344,7 @@ Robert Brown
it's good to call it <code>row</code> or <code>first-row</code> it's good to call it <code>row</code> or <code>first-row</code>
or something like that. or something like that.
It is alright is <code>row</code> has been It is alright is <code>row</code> has been
<code>DEFTYPE</code>'d to <code>STRING</code> &#8212; <code>DEFTYPE</code>'d to <code>STRING</code> —
precisely because you have abstracted the detail away, precisely because you have abstracted the detail away,
and the remaining salient point is that it is a row. and the remaining salient point is that it is a row.
You should not name the variable <code>STRING</code> in this context, You should not name the variable <code>STRING</code> in this context,
@ -1627,7 +1627,7 @@ Robert Brown
<p> <p>
Common Lisp systems are not required to implement Common Lisp systems are not required to implement
function calls from tail positions without leaking stack space function calls from tail positions without leaking stack space
&#8212; which is known as proper tail calls (PTC), — which is known as proper tail calls (PTC),
tail call elimination (TCE), tail call elimination (TCE),
or tail call optimization (TCO). or tail call optimization (TCO).
This means that indefinite recursion through tail calls This means that indefinite recursion through tail calls
@ -1886,7 +1886,7 @@ Robert Brown
</li> </li>
<li> <li>
<code>(error (make-condition 'foo-error ...))</code> <code>(error (make-condition 'foo-error ...))</code>
is equivalent to <code>(error 'foo-error ...)</code> &#8212; is equivalent to <code>(error 'foo-error ...)</code> —
code must use the shorter form. code must use the shorter form.
</li> </li>
<li> <li>
@ -2241,7 +2241,7 @@ Robert Brown
When you write a macro-defining macro When you write a macro-defining macro
(a macro that generates macros), (a macro that generates macros),
document and comment it particularly clearly, document and comment it particularly clearly,
since these are hard for the uninitiated to understand. since these are harder to understand.
</p> </p>
<p> <p>
You must not install new reader macros You must not install new reader macros
@ -2284,7 +2284,7 @@ Robert Brown
By keeping semantics outside the macro, By keeping semantics outside the macro,
the macro is made simpler, easier to get right, and less subject to change, the macro is made simpler, easier to get right, and less subject to change,
which makes it easier to develop and maintain. which makes it easier to develop and maintain.
The semantics is written in a simpler language &#8212; one without staging &#8212; The semantics is written in a simpler language — one without staging —
which also makes it easier to develop and maintain. which also makes it easier to develop and maintain.
It becomes possible to debug and update the semantic function It becomes possible to debug and update the semantic function
without having to recompile all clients of the macro. without having to recompile all clients of the macro.
@ -2304,7 +2304,7 @@ Robert Brown
which can be done using <code>FLET</code>. which can be done using <code>FLET</code>.
This also allows you to declare the function to be of dynamic extent This also allows you to declare the function to be of dynamic extent
(if it is &#8212; and often it is; yet see below regarding (if it is — and often it is; yet see below regarding
<a href="#DYNAMIC-EXTENT">DYNAMIC-EXTENT</a>). <a href="#DYNAMIC-EXTENT">DYNAMIC-EXTENT</a>).
</p> </p>
<p> <p>
@ -2986,7 +2986,7 @@ Robert Brown
</p> </p>
<p> <p>
However, don't use <code>PROGN</code> for an <code>IF</code> clause However, don't use <code>PROGN</code> for an <code>IF</code> clause
&#8212; use <code>COND</code>, <code>WHEN</code>, or <code>UNLESS</code>. — use <code>COND</code>, <code>WHEN</code>, or <code>UNLESS</code>.
</p> </p>
<p> <p>
Note that in Common Lisp, Note that in Common Lisp,
@ -3237,7 +3237,7 @@ Robert Brown
</p> </p>
<p> <p>
Code must not use <code>PRINT-OBJECT</code> Code must not use <code>PRINT-OBJECT</code>
to communicate with a user &#8212; to communicate with a user —
<code>PRINT-OBJECT</code> is for debugging purposes only. <code>PRINT-OBJECT</code> is for debugging purposes only.
Modifying any <code>PRINT-OBJECT</code> method Modifying any <code>PRINT-OBJECT</code> method
must not break any public interfaces. must not break any public interfaces.
@ -3464,7 +3464,7 @@ Robert Brown
If the assertion is wrong, i.e. if the programmer's claim is not true, If the assertion is wrong, i.e. if the programmer's claim is not true,
the results can be <em>catastrophic</em>: the results can be <em>catastrophic</em>:
Lisp can terminate any time after the function returns, Lisp can terminate any time after the function returns,
or it hang forever, or &#8212; worst of all &#8212; or it hang forever, or — worst of all —
produce incorrect results without any runtime error! produce incorrect results without any runtime error!
</p> </p>
<p> <p>
@ -3693,7 +3693,7 @@ Robert Brown
in a heavily functional style, in a heavily functional style,
you may consider using you may consider using
<a href="http://cliki.net/lambda-reader">lambda-reader</a>, <a href="http://cliki.net/lambda-reader">lambda-reader</a>,
a system that lets you use the unicode character <code>&#955;</code> a system that lets you use the unicode character <code>λ</code>
instead of <code>LAMBDA</code>. instead of <code>LAMBDA</code>.
But you must not start using such a syntactic extension But you must not start using such a syntactic extension
in an existing system without getting permission from other developers. in an existing system without getting permission from other developers.
@ -3890,7 +3890,7 @@ Robert Brown
</small> </small>
<p align="right"> <p align="right">
Revision 1.17 Revision 1.18
</p> </p>
@ -3899,7 +3899,7 @@ Robert Brown
</address> </address>
<address> <address>
<a HREF="mailto:tunes@google.com">Fran&#231;ois-Ren&#233; Rideau</a> <a HREF="mailto:tunes@google.com">François-René Rideau</a>
</address> </address>

32
objcguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 2.48 Revision 2.52
</p> </p>
@ -564,7 +564,7 @@ Revision 2.48
<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&#8212;including case. Follow the convention that your they contain—including case. Follow the convention that your
project project
uses. uses.
@ -700,6 +700,18 @@ Revision 2.48
There should be a single space between the class name and the opening There should be a single space between the class name and the opening
parenthesis of the category. parenthesis of the category.
</p> </p>
<CODE_SNIPPET>
// Extending a framework class:
@interface NSString (GTMStringParsingAdditions)
- (NSString *)gtm_foobarString;
@end
// Making your methods and properties private:
@interface FoobarViewController ()
@property(nonatomic, retain) NSView *dongleView;
- (void)performLayout;
@end
</CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -805,7 +817,7 @@ Revision 2.48
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—the next
one may be you! one may be you!
</p> </p>
<p> <p>
@ -1061,7 +1073,7 @@ Revision 2.48
<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—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
@ -1681,6 +1693,11 @@ Revision 2.48
the default. Properties, on the other hand, should always specify the the default. Properties, on the other hand, should always specify the
<code>strong</code> keyword rather than relying on the compiler default. <code>strong</code> keyword rather than relying on the compiler default.
</p> </p>
<p>
Files that are compiled using ARC need to have preprocessor directives
to prevent compilation without ARC. See the code snippet below for
details.
</p>
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -1695,9 +1712,8 @@ Revision 2.48
#import "Foo.h" #import "Foo.h"
@implementation Foo { @implementation Foo {
@private Bar* __weak _bar;
Bar * __weak _bar; Baz* __unsafe_unretained _baz;
Baz * __unsafe_unretained _baz;
} }
// ... // ...
@end @end
@ -1822,7 +1838,7 @@ Revision 2.48
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 2.48 Revision 2.52
</p> </p>

25
pyguide.html
View File

@ -136,7 +136,7 @@
<H1>Google Python Style Guide</H1> <H1>Google Python Style Guide</H1>
<p align="right"> <p align="right">
Revision 2.45 Revision 2.48
</p> </p>
<address> <address>
@ -1246,9 +1246,11 @@ from sound.effects import echo
</DIV> </DIV>
<DIV class=""><DIV class="stylepoint_body" name="Line_length__body" id="Line_length__body" style="display: none"> <DIV class=""><DIV class="stylepoint_body" name="Line_length__body" id="Line_length__body" style="display: none">
<p> <p>
Exception: lines importing modules may end up longer than 80 Exceptions:
characters only if using Python 2.4 or <ul>
earlier. <li>Long import statements.</li>
<li>URLs in comments.</li>
</ul>
</p> </p>
<p> <p>
@ -1258,7 +1260,7 @@ from sound.effects import echo
<p> <p>
Make use of Python's Make use of Python's
<a HREF="http://www.python.org/doc/ref/implicit-joining.html">implicit <a HREF="http://docs.python.org/reference/lexical_analysis.html#implicit-line-joining">implicit
line joining inside parentheses, brackets and braces</a>. line joining inside parentheses, brackets and braces</a>.
If necessary, you can add an extra pair of parentheses around an If necessary, you can add an extra pair of parentheses around an
expression. expression.
@ -1281,6 +1283,17 @@ from sound.effects import echo
<span class="external"></span>x = ('This will build a very long long ' <span class="external"></span>x = ('This will build a very long long '
<span class="external"></span> 'long long long long long long string')</PRE></DIV> <span class="external"></span> 'long long long long long long string')</PRE></DIV>
<p>
Within comments, put long URLs on their own line if necessary.
</p>
<DIV class=""><PRE>Yes: <span class="external"></span># See details at
<span class="external"></span># http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html</PRE></DIV>
<DIV class=""><PRE class="badcode">No: <span class="external"></span># See details at
<span class="external"></span># http://www.example.com/us/developer/documentation/api/content/\
<span class="external"></span># v2.0/csv_file_name_extension_full_specification.html</PRE></DIV>
<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
@ -2223,7 +2236,7 @@ Don'<span class="external"></span>t do this.
<p align="right"> <p align="right">
Revision 2.45 Revision 2.48
</p> </p>