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">
Revision 3.231
Revision 3.245
</p>
@ -364,7 +364,7 @@ Tashana Landray
</p>
<ol>
<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> Other libraries' <code>.h</code> files.</li>
@ -779,6 +779,8 @@ Tashana Landray
Static or global variables of class type are forbidden: they cause
hard-to-find bugs due to indeterminate order of construction and
destruction.
However, such variables are allowed if they are <code>constexpr</code>:
they have no dynamic initialization or destruction.
</SUMMARY>
<BODY>
<p>
@ -1560,7 +1562,8 @@ Tashana Landray
arguments are values or <code>const</code> references while
output arguments are pointers. Input parameters may be
<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>
@ -2159,6 +2162,8 @@ Tashana Landray
<STYLEPOINT title="Use of const">
<SUMMARY>
Use <code>const</code> whenever it makes sense.
With C++11,
<code>constexpr</code> is a better choice for some uses of const.
</SUMMARY>
<BODY>
<DEFINITION>
@ -2243,6 +2248,51 @@ Tashana Landray
</BODY>
</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">
<SUMMARY>
Of the built-in C++ integer types, the only one used
@ -2251,7 +2301,12 @@ Tashana Landray
size, use
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>
<BODY>
<DEFINITION>
@ -2301,14 +2356,24 @@ Tashana Landray
<p>
You should not use the unsigned integer types such as
<code>uint32_t</code>,
unless the quantity you are representing is really a bit pattern
rather than a number, or unless you need defined
twos-complement overflow. In particular, do not use unsigned
types to say a number will never be negative. Instead, use
unless there is a valid reason such as representing a bit pattern
rather than a number, or you need defined overflow modulo 2^N.
In particular, do not use unsigned types to say a number will never
be negative. Instead, use
assertions for this.
</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>
<SUBSECTION title="On Unsigned Integers">
@ -2571,16 +2636,21 @@ Tashana Landray
<STYLEPOINT title="sizeof">
<SUMMARY>
Use <code>sizeof(<var>varname</var>)</code> instead of
<code>sizeof(<var>type</var>)</code> whenever possible.
Prefer <code>sizeof(<var>varname</var>)</code> to
<code>sizeof(<var>type</var>)</code>.
</SUMMARY>
<BODY>
<p>
Use <code>sizeof(<var>varname</var>)</code> because it will update
appropriately if the type of the variable changes.
<code>sizeof(<var>type</var>)</code> may make sense in some cases,
but should generally be avoided because it can fall out of sync if
the variable's type changes.
Use <code>sizeof(<var>varname</var>)</code>
when you take the size of a particular variable.
<code>sizeof(<var>varname</var>)</code> will update
appropriately if someone changes the variable type
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>
<CODE_SNIPPET>
@ -2590,6 +2660,12 @@ Tashana Landray
<BAD_CODE_SNIPPET>
memset(&amp;data, 0, sizeof(Struct));
</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>
</BODY>
</STYLEPOINT>
@ -2666,7 +2742,7 @@ Tashana Landray
auto x(3); // Note: parentheses.
auto y{3}; // Note: curly braces.
</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>initializer_list</code>. The same applies to other
normally-invisible proxy types.
@ -2752,6 +2828,13 @@ Tashana Landray
<code>boost/iterator/iterator_adaptor.hpp</code>,
<code>boost/iterator/iterator_facade.hpp</code>, and
<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>
We are actively considering adding other Boost features to the list, so
this rule may be relaxed in the future.
@ -2795,7 +2878,7 @@ Tashana Landray
</p>
<p>
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,
or by encouraging template metaprogramming. Other extensions
duplicate functionality available through existing
@ -2809,6 +2892,8 @@ Tashana Landray
Currently only the following C++11 features are approved:
<ul>
<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
close multiple levels of template arguments, as in
<code>set&lt;list&lt;string&gt;&gt;</code>,
@ -2830,6 +2915,9 @@ Tashana Landray
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>
<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>
Other features will be approved individually as appropriate.
Avoid writing code that is incompatible with C++11 (even though it
@ -2995,8 +3083,8 @@ Tashana Landray
</SUMMARY>
<BODY>
<p>
The names of all types &#8212; classes, structs, typedefs, and enums
&#8212; have the same naming convention. Type names should start
The names of all types — classes, structs, typedefs, and enums
— have the same naming convention. Type names should start
with a capital letter and have a capital letter for each new
word. No underscores. For example:
</p>
@ -3267,7 +3355,7 @@ Tashana Landray
When writing your comments, write for your audience: the next
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!
</p>
@ -3802,7 +3890,7 @@ Tashana Landray
an encoding understood by most tools able
to handle more than just ASCII.
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
invisible if included in the source as straight UTF-8.
</p>
@ -3956,22 +4044,26 @@ Tashana Landray
argument4);
</CODE_SNIPPET>
<p>
If the function signature is so long that it cannot fit within
the maximum <a href="#Line_Length">line length</a>, you may
place all arguments on subsequent lines:
Arguments may optionally all be placed on subsequent lines, with one
line per argument:
</p>
<CODE_SNIPPET>
if (...) {
...
...
if (...) {
DoSomethingThatRequiresALongFunctionName(
very_long_argument1, // 4 space indent
DoSomething(
argument1, // 4 space indent
argument2,
argument3,
argument4);
}
</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>
</STYLEPOINT>
@ -4097,8 +4189,9 @@ Tashana Landray
<STYLEPOINT title="Loops and Switch Statements">
<SUMMARY>
Switch statements may use braces for blocks. Empty loop bodies should use
<code>{}</code> or <code>continue</code>.
Switch statements may use braces for blocks. Annotate non-trivial
fall-through between cases. Empty loop bodies should use <code>{}</code>
or <code>continue</code>.
</SUMMARY>
<BODY>
<p>
@ -4130,6 +4223,8 @@ Tashana Landray
}
}
</CODE_SNIPPET>
<p>
Empty loop bodies should use <code>{}</code> or
<code>continue</code>, but not a single semicolon.
@ -4708,7 +4803,7 @@ Tashana Landray
<HR/>
<p align="right">
Revision 3.231
Revision 3.245
</p>

178
htmlcssguide.xml
View File

@ -3,22 +3,22 @@
<GUIDE title="Google HTML/CSS Style Guide">
<p class="revision">
Revision 2.19
Revision 2.21
</p>
<OVERVIEW>
<CATEGORY title="Important Note">
<STYLEPOINT title="Displaying Hidden Details in this Guide">
<STYLEPOINT title="Displaying Hidden Details in This Guide">
<SUMMARY>
This style guide contains many details that are initially
hidden from view. They are marked by the triangle icon, which you
see here on your left. Click it now.
You should see &#8220;Hooray&#8221; appear below.
You should see “Hooray” appear below.
</SUMMARY>
<BODY>
<p>
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.
</p>
</BODY>
@ -52,8 +52,8 @@
files are not available over both protocols.
</p>
<p>
Omitting the protocol&#8212;which makes the URL
relative&#8212;prevents mixed content issues and results in
Omitting the protocol—which makes the URL
relative—prevents mixed content issues and results in
minor file size savings.
</p>
<BAD_CODE_SNIPPET>
@ -88,7 +88,7 @@
</SUMMARY>
<BODY>
<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>
<CODE_SNIPPET>
&lt;ul&gt;
@ -109,9 +109,9 @@
</SUMMARY>
<BODY>
<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
text/<code>CDATA</code>), selectors, properties, and
<code>text/CDATA</code>), CSS selectors, properties, and
property values (with the exception of strings).
</p>
<BAD_CODE_SNIPPET>
@ -122,9 +122,17 @@
&lt;!-- Recommended --&gt;
&lt;img src="google.png" alt="Google"&gt;
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
/* Not recommended */
color: #E5E5E5;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
color: #e5e5e5;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Trailing whitespace">
<STYLEPOINT title="Trailing Whitespace">
<SUMMARY>
Remove trailing white spaces.
</SUMMARY>
@ -181,11 +189,11 @@
(This item is optional as it is not deemed a realistic
expectation to always demand fully documented code. Mileage
may vary heavily for HTML and CSS code and depends on the
project&#8217;s complexity.)
project’s complexity.)
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Action items">
<STYLEPOINT title="Action Items">
<SUMMARY>
Mark todos and action items with <code>TODO</code>.
</SUMMARY>
@ -220,7 +228,7 @@
</CATEGORY>
<CATEGORY title="HTML Style Rules">
<STYLEPOINT title="Document type">
<STYLEPOINT title="Document Type">
<SUMMARY>
Use HTML5.
</SUMMARY>
@ -230,7 +238,7 @@
<code>&lt;!DOCTYPE html&gt;</code>.
</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>,
lacks both browser and infrastructure support and offers
less room for optimization than HTML.)
@ -241,7 +249,7 @@
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="HTML validity">
<STYLEPOINT title="HTML Validity">
<SUMMARY>
Use valid HTML where possible.
</SUMMARY>
@ -252,8 +260,7 @@
</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.
</p>
<p>
@ -281,7 +288,7 @@
</SUMMARY>
<BODY>
<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
elements for headings, <code>p</code> elements for
paragraphs, <code>a</code> elements for anchors, etc.
@ -301,7 +308,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Multimedia fallback">
<STYLEPOINT title="Multimedia Fallback">
<SUMMARY>
Provide alternative contents for multimedia.
</SUMMARY>
@ -338,7 +345,7 @@
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Separation of concerns">
<STYLEPOINT title="Separation of Concerns">
<SUMMARY>
Separate structure from presentation from behavior.
</SUMMARY>
@ -374,9 +381,9 @@
&lt;link rel="stylesheet" href="grid.css" media="screen"&gt;
&lt;link rel="stylesheet" href="print.css" media="print"&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;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;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
@ -385,14 +392,14 @@
&lt;title&gt;My first CSS-only redesign&lt;/title&gt;
&lt;link rel="stylesheet" href="default.css"&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
my website that is presentational.
&lt;p&gt;It&#8217;s awesome!
&lt;p&gt;It’s awesome!
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Entity references">
<STYLEPOINT title="Entity References">
<SUMMARY>
Do not use entity references.
</SUMMARY>
@ -407,7 +414,7 @@
<p>
The only exceptions apply to characters with special meaning
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).
</p>
<BAD_CODE_SNIPPET>
@ -416,11 +423,11 @@
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
The currency symbol for the Euro is &#8220;&#8364;&#8221;.
The currency symbol for the Euro is “€”.
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Optional tags">
<STYLEPOINT title="Optional Tags">
<SUMMARY>
Omit optional tags (optional).
</SUMMARY>
@ -433,9 +440,9 @@
</p>
<p>
(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
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.)
</p>
<BAD_CODE_SNIPPET>
@ -458,7 +465,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="type attributes">
<STYLEPOINT title="type Attributes">
<SUMMARY>
Omit <code>type</code> attributes for style sheets and scripts.
</SUMMARY>
@ -499,7 +506,7 @@
</CATEGORY>
<CATEGORY title="HTML Formatting Rules">
<STYLEPOINT title="General formatting">
<STYLEPOINT title="General Formatting">
<SUMMARY>
Use a new line for every block, list, or table element, and
indent every such child element.
@ -517,7 +524,7 @@
</p>
<p>
(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
an error.)
</p>
@ -547,7 +554,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="HTML quotation marks">
<STYLEPOINT title="HTML Quotation Marks">
<SUMMARY>
When quoting attributes values, use double quotation marks.
</SUMMARY>
@ -569,7 +576,7 @@
</CATEGORY>
<CATEGORY title="CSS Style Rules">
<STYLEPOINT title="CSS validity">
<STYLEPOINT title="CSS Validity">
<SUMMARY>
Use valid CSS where possible.
</SUMMARY>
@ -580,8 +587,7 @@
</p>
<p>
Use tools such as the
<a href="http://jigsaw.w3.org/css-validator/">W3C
Use tools such as the <a href="http://jigsaw.w3.org/css-validator/">W3C
CSS validator</a> to test.
</p>
<p>
@ -591,7 +597,7 @@
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="ID and class naming">
<STYLEPOINT title="ID and Class Naming">
<SUMMARY>
Use meaningful or generic ID and class names.
</SUMMARY>
@ -609,7 +615,7 @@
<p>
Generic names are simply a fallback for elements that have no
particular or no meaning different from their siblings. They are
typically needed as &#8220;helpers.&#8221;
typically needed as “helpers.”
</p>
<p>
Using functional or generic names reduces the probability of
@ -635,7 +641,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="ID and class name style">
<STYLEPOINT title="ID and Class Name Style">
<SUMMARY>
Use ID and class names that are as short as possible but as long as
necessary.
@ -662,7 +668,7 @@
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Type selectors">
<STYLEPOINT title="Type Selectors">
<SUMMARY>
Avoid qualifying ID and class names with type selectors.
</SUMMARY>
@ -671,8 +677,7 @@
use element names in conjunction with IDs or classes.
</p>
<p>
Avoiding unnecessary ancestor selectors is useful for
<a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance
Avoiding unnecessary ancestor selectors is useful for <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance
reasons</a>.
</p>
<BAD_CODE_SNIPPET>
@ -687,14 +692,13 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Shorthand properties">
<STYLEPOINT title="Shorthand Properties">
<SUMMARY>
Use shorthand properties where possible.
</SUMMARY>
<BODY>
<p>
CSS offers a variety of
<a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
CSS offers a variety of <a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
properties (like <code>font</code>)
that should be used whenever possible, even in cases where
only one value is explicitly set.
@ -722,9 +726,9 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="0 and units">
<STYLEPOINT title="0 and Units">
<SUMMARY>
Omit unit specification after &#8220;0&#8221; values.
Omit unit specification after “0” values.
</SUMMARY>
<BODY>
<p>
@ -739,7 +743,7 @@
</STYLEPOINT>
<STYLEPOINT title="Leading 0s">
<SUMMARY>
Omit leading &#8220;0&#8221;s in values.
Omit leading “0”s in values.
</SUMMARY>
<BODY>
<p>
@ -751,7 +755,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Hexadecimal notation">
<STYLEPOINT title="Hexadecimal Notation">
<SUMMARY>
Use 3 character hexadecimal notation where possible.
</SUMMARY>
@ -794,7 +798,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="ID and class name delimiters">
<STYLEPOINT title="ID and Class Name Delimiters">
<SUMMARY>
Separate words in ID and class names by a hyphen.
</SUMMARY>
@ -805,7 +809,7 @@
in order to improve understanding and scannability.
</p>
<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 {}
/* Not recommended: uses underscore instead of hyphen */
@ -820,12 +824,12 @@
</STYLEPOINT>
<STYLEPOINT title="Hacks">
<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.
</SUMMARY>
<BODY>
<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
hacks. Both approaches should be considered last resort in
order to achieve and maintain an efficient and manageable
@ -833,7 +837,7 @@
free pass will hurt projects in the long run as projects
tend to take the way of least resistance. That is, allowing
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.
</p>
@ -843,7 +847,7 @@
</CATEGORY>
<CATEGORY title="CSS Formatting Rules">
<STYLEPOINT title="Declaration order">
<STYLEPOINT title="Declaration Order">
<SUMMARY>
Alphabetize declarations.
</SUMMARY>
@ -870,7 +874,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Block content indentation">
<STYLEPOINT title="Block Content Indentation">
<SUMMARY>
Indent all block content.
</SUMMARY>
@ -892,7 +896,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Declaration stops">
<STYLEPOINT title="Declaration Stops">
<SUMMARY>
Use a semicolon after every declaration.
</SUMMARY>
@ -917,9 +921,9 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Property name stops">
<STYLEPOINT title="Property Name Stops">
<SUMMARY>
Use a space after a property name&#8217;s colon.
Use a space after a property name’s colon.
</SUMMARY>
<BODY>
<p>
@ -940,7 +944,41 @@
</CODE_SNIPPET>
</BODY>
</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>
Separate selectors and declarations by new lines.
</SUMMARY>
@ -965,13 +1003,13 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Rule separation">
<STYLEPOINT title="Rule Separation">
<SUMMARY>
Separate rules by new lines.
</SUMMARY>
<BODY>
<p>
Always put a line between rules.
Always put a blank line (two line breaks) between rules.
</p>
<CODE_SNIPPET>
html {
@ -985,7 +1023,7 @@
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="CSS quotation marks">
<STYLEPOINT title="CSS Quotation Marks">
<SUMMARY>
Use single quotation marks for attribute selectors and property values.
</SUMMARY>
@ -997,7 +1035,7 @@
</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
use double quotation marks—<a href="http://www.w3.org/TR/CSS21/syndata.html#charset">single
quotation marks are not permitted</a>.
</p>
<BAD_CODE_SNIPPET>
@ -1022,7 +1060,7 @@
<CATEGORY title="CSS Meta Rules">
<STYLEPOINT title="Section comments">
<STYLEPOINT title="Section Comments">
<SUMMARY>
Group sections by a section comment (optional).
</SUMMARY>
@ -1053,7 +1091,7 @@
<em>Be consistent.</em>
</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
all their arithmetic operators, you should too. If their
comments have little boxes of hash marks around them, make your
@ -1061,8 +1099,8 @@
</p>
<p>
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
than on how you&#8217;re saying it. We present global style rules here so
of coding so people can concentrate on what you’re saying rather
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
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
@ -1071,7 +1109,7 @@
</PARTING_WORDS>
<p align="right">
Revision 2.19
Revision 2.21
</p>
</GUIDE>

50
javascriptguide.xml
View File

@ -3,14 +3,14 @@
<GUIDE title="Google JavaScript Style Guide">
<p class="revision">
Revision 2.64
Revision 2.72
</p>
<address>
Aaron Whyte<br/>
Bob Jervis<br/>
Dan Pupius<br/>
Eric Arvidsson<br/>
Erik Arvidsson<br/>
Fritz Schneider<br/>
Robby Walker<br/>
</address>
@ -96,7 +96,7 @@
<code>boolean</code>) are constant values.</p>
<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
state change. This is not enforced by the compiler.</p>
@ -729,11 +729,10 @@
<BODY>
<SUBSECTION title="Properties and methods">
<ul>
<li><em>Private</em> properties, variables, and methods (in files
or classes) should be named with a trailing
underscore.
<li><em>Private</em> properties and methods should be named with a
trailing underscore.
</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>
</ul>
<p>For more information on <em>private</em> and <em>protected</em>,
@ -892,7 +891,8 @@
staticHelper(new MyClass());
};
</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>
myapp.main = function() {
var namespace = some.long.namespace;
@ -999,7 +999,7 @@
var obj = {a: 1, b: 2, c: 3}; // No space after { or before }.
</CODE_SNIPPET>
<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>
// Object initializer.
var inset = {
@ -1127,6 +1127,7 @@
</CODE_SNIPPET>
</SUBSECTION>
<SUBSECTION title="Aliasing with goog.scope">
<a name="goog-scope"/>
<p>
<a href="https://docs.google.com/document/pub?id=1ETFAuh2kaXMVL-vafUYhaWlhl6b5D9TOvboVg7Zl68Y"><code>goog.scope</code></a>
may be used to shorten references to
@ -2204,7 +2205,10 @@
<p>All files, classes, methods and properties should be documented with
<a href="http://code.google.com/p/jsdoc-toolkit/">JSDoc</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>
@ -2438,15 +2442,15 @@
<tr>
<td><a name="tag-const">@const</a></td>
<td>
<code>@const</code>
<code>@const</code><br/>
<code>@const {type}</code>
<p><i>For example:</i></p>
<CODE_SNIPPET>
/** @const */ var MY_BEER = 'stout';
/**
* My namespace's favorite kind of beer.
* @const
* @type {string}
* @const {string}
*/
mynamespace.MY_BEER = 'stout';
@ -2476,7 +2480,7 @@
<p>When <code>@const</code> is applied to a method, it
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>
<p>For more on <code>@const</code>, see the
@ -2861,6 +2865,10 @@
</td>
</tr>
<tr>
<td><a name="tag-noalias">@noalias</a></td>
<td>
@ -2962,13 +2970,13 @@
<tr>
<td><a name="tag-private">@private</a></td>
<td>
<code>@private</code>
<code>@private</code><br/>
<code>@private {type}</code>
<p><i>For example:</i></p>
<CODE_SNIPPET>
/**
* Handlers that are listening to this logger.
* @type Array.&lt;Function&gt;
* @private
* @private {!Array.&lt;Function&gt;}
*/
this.handlers_ = [];
</CODE_SNIPPET>
@ -2985,7 +2993,8 @@
<tr>
<td><a name="tag-protected">@protected</a></td>
<td>
<code>@protected</code>
<code>@protected</code><br/>
<code>@protected {type}</code>
<p><i>For example:</i></p>
<CODE_SNIPPET>
/**
@ -3222,6 +3231,9 @@
<a href="#Typedefs">complex type</a>.
</td>
</tr>
</tbody>
</table>
@ -3527,7 +3539,7 @@
</PARTING_WORDS>
<p align="right">
Revision 2.64
Revision 2.72
</p>

38
lispguide.xml
View File

@ -5,7 +5,7 @@
<p align="right">
Revision 1.17
Revision 1.18
</p>
@ -13,7 +13,7 @@ Revision 1.17
Robert Brown
</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>
@ -21,7 +21,7 @@ Robert Brown
</address>
<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>
@ -305,7 +305,7 @@ Robert Brown
<li>
Every developer's code must be easy for another developer
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.)
</li>
<li>
@ -314,7 +314,7 @@ Robert Brown
and recognize it as "Fred's code" by its style.
</li>
<li>
Don't be "clever" &#8212;
Don't be "clever" —
do the simplest thing that could possibly work properly.
</li>
<li>
@ -324,7 +324,7 @@ Robert Brown
Be concise.
</li>
<li>
KISS &#8212; Keep It Simple, Stupid.
KISS — Keep It Simple, Stupid.
</li>
<li>
Use the smallest hammer for the job.
@ -411,7 +411,7 @@ Robert Brown
(including QA or Ops), or otherwise isn't purely local,
you must write it up using at least a couple of paragraphs,
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.
</p>
<p>
@ -1344,7 +1344,7 @@ Robert Brown
it's good to call it <code>row</code> or <code>first-row</code>
or something like that.
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,
and the remaining salient point is that it is a row.
You should not name the variable <code>STRING</code> in this context,
@ -1627,7 +1627,7 @@ Robert Brown
<p>
Common Lisp systems are not required to implement
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),
or tail call optimization (TCO).
This means that indefinite recursion through tail calls
@ -1886,7 +1886,7 @@ Robert Brown
</li>
<li>
<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.
</li>
<li>
@ -2241,7 +2241,7 @@ Robert Brown
When you write a macro-defining macro
(a macro that generates macros),
document and comment it particularly clearly,
since these are hard for the uninitiated to understand.
since these are harder to understand.
</p>
<p>
You must not install new reader macros
@ -2284,7 +2284,7 @@ Robert Brown
By keeping semantics outside the macro,
the macro is made simpler, easier to get right, and less subject to change,
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.
It becomes possible to debug and update the semantic function
without having to recompile all clients of the macro.
@ -2304,7 +2304,7 @@ Robert Brown
which can be done using <code>FLET</code>.
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>).
</p>
<p>
@ -2986,7 +2986,7 @@ Robert Brown
</p>
<p>
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>
Note that in Common Lisp,
@ -3237,7 +3237,7 @@ Robert Brown
</p>
<p>
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.
Modifying any <code>PRINT-OBJECT</code> method
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,
the results can be <em>catastrophic</em>:
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!
</p>
<p>
@ -3693,7 +3693,7 @@ Robert Brown
in a heavily functional style,
you may consider using
<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>.
But you must not start using such a syntactic extension
in an existing system without getting permission from other developers.
@ -3890,7 +3890,7 @@ Robert Brown
</small>
<p align="right">
Revision 1.17
Revision 1.18
</p>
@ -3899,7 +3899,7 @@ Robert Brown
</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>

32
objcguide.xml
View File

@ -4,7 +4,7 @@
<p align="right">
Revision 2.48
Revision 2.52
</p>
@ -564,7 +564,7 @@ Revision 2.48
<STYLEPOINT title="File Names">
<SUMMARY>
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
uses.
@ -700,6 +700,18 @@ Revision 2.48
There should be a single space between the class name and the opening
parenthesis of the category.
</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>
</STYLEPOINT>
@ -805,7 +817,7 @@ Revision 2.48
When writing your comments, write for your audience: the next
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!
</p>
<p>
@ -1061,7 +1073,7 @@ Revision 2.48
<BODY>
<p>
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
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
@ -1681,6 +1693,11 @@ Revision 2.48
the default. Properties, on the other hand, should always specify the
<code>strong</code> keyword rather than relying on the compiler default.
</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>
<BODY>
<p>
@ -1695,9 +1712,8 @@ Revision 2.48
#import "Foo.h"
@implementation Foo {
@private
Bar * __weak _bar;
Baz * __unsafe_unretained _baz;
Bar* __weak _bar;
Baz* __unsafe_unretained _baz;
}
// ...
@end
@ -1822,7 +1838,7 @@ Revision 2.48
<HR/>
<p align="right">
Revision 2.48
Revision 2.52
</p>

25
pyguide.html
View File

@ -136,7 +136,7 @@
<H1>Google Python Style Guide</H1>
<p align="right">
Revision 2.45
Revision 2.48
</p>
<address>
@ -1246,9 +1246,11 @@ from sound.effects import echo
</DIV>
<DIV class=""><DIV class="stylepoint_body" name="Line_length__body" id="Line_length__body" style="display: none">
<p>
Exception: lines importing modules may end up longer than 80
characters only if using Python 2.4 or
earlier.
Exceptions:
<ul>
<li>Long import statements.</li>
<li>URLs in comments.</li>
</ul>
</p>
<p>
@ -1258,7 +1260,7 @@ from sound.effects import echo
<p>
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>.
If necessary, you can add an extra pair of parentheses around an
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> '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>
Make note of the indentation of the elements in the line
continuation examples above; see the
@ -2223,7 +2236,7 @@ Don'<span class="external"></span>t do this.
<p align="right">
Revision 2.45
Revision 2.48
</p>