Skip to content

Commit

Permalink
Update C++ style guide to 3.199:
Browse files Browse the repository at this point in the history 
 - Update an example to omit the blank line between C and C++ #includes.
 - Rewrite the paragraph about #include ordering.
 - Clarify namespace closing comments.
 - Discourage const references for input arguments which are aliased beyond
   the scope of the function call.
 - Replace all '&' with '&'.
 - Clarify that interfaces must have virtual destructors.
 - Add an explicit example for |else if|.
 - C++11 updates.

Update Objective-C style guide to 2.36:
 - Remove requirement to list @dynamic implementations.
 - Remove requirement to never synthesize CFType properties, since they may
   be retained on 10.6.
 - Use __weak and __strong type declaration modifiers rather than comments.
 - Make the copyright/license information consistent.
 - An example initializer comment revealed too much about the implementation.
 - Correct spelling mistakes.
 - Fix names that didn't follow Cocoa conventions.
 - Fix examples to conform to style.
 - Add a section about no braces for empty interfaces.
 - Add a section about automatically synthesized instance variables.
 - Codify avoidance of accessors in -init and -dealloc methods.
 - Changes for the 80-column rule.
 - Weaken the language around object ownership type qualifiers.
 - Document the rules for formatting blocks.

Update JavaScript style guide to 2.27:
 - Introduce EcmaScript 5 Strict verbiage.
 - Add a note about private constructors.
 - Simplify explanations about JSDoc comments.
 - Sort the JSDoc tags.
 - Remove the sections about type-checking now that the JSDoc tags and JS
   types are no longer one table.
 - Convert <tt> to <code>, because the XSL processor eats <tt>.
 - Add @Suppress.
 - Mark @inheritdoc deprecated in favor of @OverRide.
 - Add a section about inner classes and enums being defined in the same file
   as the top-level class they are defined on.

Update Python style guide to 2.28:
 - Change "Naming" summary to match body.
 - Make the prohibition against backslash line continuation explicit.
 - Update the TODO section to match the C++ style guide.
 - Declare Python code without a shebang line to be stylish.
 - Clarify rules on function docstrings.
 - Fix spelling errors.
 - Update with styleguide.xsl 1.33.

Update styleguide.xsl to 1.33:
 - Clean up style guide JS.
 - Links to anchor tags auto-expand.
  • Loading branch information
[email protected] committed Nov 4, 2011
1 parent 8a95ecc commit e33361f
Show file tree
Hide file tree
Showing 5 changed files with 1,222 additions and 1,002 deletions.
83 changes: 49 additions & 34 deletions cppguide.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

<p align="right">

Revision 3.188
Revision 3.199
</p>


Expand Down Expand Up @@ -209,7 +209,6 @@ Tashana Landray
definitions of the classes they use, and usually have to
include several header files.
</p>

<SUBSECTION title="Note:">
If you use a symbol <code>Foo</code> in your source file, you
should bring in a definition for <code>Foo</code> yourself,
Expand Down Expand Up @@ -383,11 +382,13 @@ Tashana Landray
<code>.h</code> files.</li>
</ol>
<p>
The preferred ordering reduces hidden dependencies. We want
every header file to be compilable on its own. The easiest
way to achieve this is to make sure that every one of them is
the first <code>.h</code> file <code>#include</code>d in some
<code>.cc</code>.
With the preferred ordering, if <code><var>dir/foo2</var>.h</code>
omits any necessary includes, the build of
<code><var>dir/foo</var>.cc</code> or
<code><var>dir/foo</var>_test.cc</code> will break.
Thus, this rule ensures that build breaks show up first
for the people working on these files, not for innocent people
in other packages.
</p>
<p>
<code><var>dir/foo</var>.cc</code> and
Expand All @@ -412,7 +413,6 @@ Tashana Landray

#include &lt;sys/types.h&gt;
#include &lt;unistd.h&gt;

#include &lt;hash_map&gt;
#include &lt;vector&gt;

Expand Down Expand Up @@ -468,6 +468,7 @@ Tashana Landray
<DECISION>
<p>
Use namespaces according to the policy described below.
Terminate namespaces with comments as shown in the given examples.
</p>

<SUBSECTION title="Unnamed Namespaces">
Expand All @@ -490,9 +491,7 @@ Tashana Landray
associated with a particular class may be declared
in that class as types, static data members or
static member functions rather than as members of
an unnamed namespace. Terminate the unnamed
namespace as shown, with a comment <code>//
namespace</code>.
an unnamed namespace.
</p>
</li>
<li> Do not use unnamed namespaces in <code>.h</code>
Expand Down Expand Up @@ -1239,7 +1238,7 @@ Tashana Landray
An interface class can never be directly instantiated
because of the pure virtual method(s) it declares. To make
sure all implementations of the interface can be destroyed
correctly, they must also declare a virtual destructor (in
correctly, the interface must also declare a virtual destructor (in
an exception to the first rule, this should not be pure). See
Stroustrup, <cite>The C++ Programming Language</cite>, 3rd
edition, section 12.4 for details.
Expand Down Expand Up @@ -1574,14 +1573,24 @@ Tashana Landray
non-<code>const</code> reference parameters.
</p>
<p>
One case when you might want an input parameter to be a
<code>const</code> pointer is if you want to emphasize that the
argument is not copied, so it must exist for the lifetime of the
object; it is usually best to document this in comments as
well. STL adapters such as <code>bind2nd</code> and
<code>mem_fun</code> do not permit reference parameters, so
you must declare functions with pointer parameters in these
cases, too.

However, there are some instances where using <code>const T*</code>
is preferable to <code>const T&amp;</code> for input parameters. For
example:

You want to pass in NULL.

The function saves a pointer or reference to the input.


Remember that most of the time input parameters are going to be
specified as <code>const T&amp;</code>. Using <code>const T*</code>
instead communicates to the reader that the input is somehow treated
differently. So if you choose <code>const T*</code> rather than
<code>const T&amp;</code>, do so for a concrete reason; otherwise it
will likely confuse readers by making them look for an explanation
that doesn't exist.

</p>
</DECISION>
</BODY>
Expand Down Expand Up @@ -2606,36 +2615,37 @@ Tashana Landray
</BODY>
</STYLEPOINT>

<STYLEPOINT title="C++0x">
<STYLEPOINT title="C++11">
<SUMMARY>
Use only approved libraries and language extensions from C++0x.
Use only approved libraries and language extensions from C++11 (formerly
known as C++0x).
Currently, none are approved.
</SUMMARY>
<BODY>
<DEFINITION>
C++0x is the next ISO C++ standard, currently in
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3092.pdf">final
committee draft</a> form. It contains
<a href="http://en.wikipedia.org/wiki/C%2B%2B0x">significant
C++11 is the latest ISO C++ standard.
It contains
<a href="http://en.wikipedia.org/wiki/C%2B%2B11">significant
changes</a> both to the language and libraries.

</DEFINITION>
<PROS>
We expect that C++0x will become the next standard, and eventually will
C++11 has become the official standard, and eventually will
be supported by most C++ compilers. It standardizes some common C++
extensions that we use already, allows shorthands for some operations,
and has some safety improvements.
and has some performance and safety improvements.
</PROS>
<CONS>
<p>
The C++0x standard is substantialy more complex than its predecessor
The C++11 standard is substantially more complex than its predecessor
(1,300 pages versus 800 pages), and is
unfamilar to many developers. The long-term effects of some
features on code readability and maintenance are unknown. We cannot
predict when its various features will be implemented uniformly by
tools that may be of interest (gcc, icc, clang, Eclipse, etc.).
</p>
<p>
As with <a href="#Boost">Boost</a>, some C++0x extensions encourage
As with <a href="#Boost">Boost</a>, some C++11 extensions encourage
coding practices that hamper readability&#8212;for example by removing
checked redundancy (such as type names) that may be helpful to readers,
or by encouraging template metaprogramming. Other extensions
Expand All @@ -2645,9 +2655,12 @@ Tashana Landray
</p>
</CONS>
<DECISION>
Use only C++0x libraries and language features that have been approved
Use only C++11 libraries and language features that have been approved
for use. Currently, no such features are approved.
Features will be approved individually as appropriate.
Avoid writing code that is incompatible with C++11 (even though it
works in C++03).

</DECISION>
</BODY>
</STYLEPOINT>
Expand Down Expand Up @@ -3845,7 +3858,9 @@ Tashana Landray
<CODE_SNIPPET>
if (condition) { // no spaces inside parentheses
... // 2 space indent.
} else { // The else goes on the same line as the closing brace.
} else if (...) { // The else goes on the same line as the closing brace.
...
} else {
...
}
</CODE_SNIPPET>
Expand Down Expand Up @@ -4069,7 +4084,7 @@ Tashana Landray
the <code>&amp;&amp;</code> logical AND operators are at the
end of the line. This is more common in Google code, though
wrapping all operators at the beginning of the line is also
allowed. Feel free to insert extra parentheses judiciously,
allowed. Feel free to insert extra parentheses judiciously
because they can be very helpful in increasing readability
when used appropriately. Also note that you should always use the
punctuation operators, such as <code>&amp;&amp;</code> and
Expand Down Expand Up @@ -4550,7 +4565,7 @@ Tashana Landray
<HR/>

<p align="right">
Revision 3.188
Revision 3.199
</p>


Expand Down
Loading

0 comments on commit e33361f

Please sign in to comment.