Update C++ style guide to 3.154:

- Add call_traits to the set of allowed boost libraries. - Add an exception to the rule against default arguments to cover the useful case of simulating variadic functions. - Discourage the usage of ## in macros. - Clarify example: it's acceptable to declare two parameters on one line even if they don't all fit on that one line. - Fix a typo ("make use symmetric spacing"). - Change bitwise AND to logical AND in a condition. Update styleguide.xsl to 1.27: - Change a bunch of SPANs into DIVs. Update Python style guide to 2.15: - Apply styleguide.xsl 1.27, changing a bunch of SPANs into DIVs.
2009-12-03 22:25:38 +00:00 · 2009-12-03 22:25:38 +00:00 · 9ec7bd6269
parent f7facf9026
commit 9ec7bd6269
3 changed files with 466 additions and 370 deletions
--- a/cppguide.xml
+++ b/cppguide.xml
@ -4,7 +4,7 @@

 <p align="right">

-Revision 3.146
+Revision 3.154
 </p>


@ -1581,7 +1581,8 @@ Tashana Landray

  <STYLEPOINT title="Default Arguments">
    <SUMMARY>
-      We do not allow default function parameters.
+      We do not allow default function parameters, except in
+      a few uncommon situations explained below.
    </SUMMARY>
    <BODY>
      <PROS>
@ -1600,10 +1601,23 @@ Tashana Landray
        the new code.
      </CONS>
      <DECISION>
-        We require all arguments to be explicitly specified, to
-        force programmers to consider the API and the values they are
-        passing for each argument rather than silently accepting
-        defaults they may not be aware of.
+        <p>
+          Except as described below, we require all arguments to be
+          explicitly specified, to force programmers to consider the API
+          and the values they are passing for each argument rather than
+          silently accepting defaults they may not be aware of.
+        </p>
+        <p>
+          One specific exception is when default arguments are used to
+          simulate variable-length argument lists.
+        </p>
+        <CODE_SNIPPET>
+          // Support up to 4 params by using a default empty AlphaNum.
+          string StrCat(const AlphaNum &amp;a,
+                        const AlphaNum &amp;b = gEmptyAlphaNum,
+                        const AlphaNum &amp;c = gEmptyAlphaNum,
+                        const AlphaNum &amp;d = gEmptyAlphaNum);
+        </CODE_SNIPPET>
      </DECISION>
    </BODY>
  </STYLEPOINT>
@ -2411,6 +2425,9 @@ Tashana Landray
        <li> Try not to use macros that expand to unbalanced C++
             constructs, or at least document that behavior well.
             </li>
+        <li> Prefer not using <code>##</code> to generate function/class/variable
+             names.
+             </li>
      </ul>
    </BODY>
  </STYLEPOINT>
@ -2494,6 +2511,9 @@ Tashana Landray
      who might read and maintain code, we only allow an approved subset of
      Boost features.  Currently, the following libraries are permitted:
      <ul>
+        <li> <a href="http://www.boost.org/libs/utility/call_traits.htm">
+             Call Traits</a> from <code>boost/call_traits.hpp</code>
+             </li>
        <li> <a href="http://www.boost.org/libs/utility/compressed_pair.htm">
             Compressed Pair</a> from <code>boost/compressed_pair.hpp</code>
             </li>
@ -3493,8 +3513,7 @@ Tashana Landray
        If you have too much text to fit on one line:
      </p>
      <CODE_SNIPPET>
-        ReturnType ClassName::ReallyLongFunctionName(Type par_name1,
-                                                     Type par_name2,
+        ReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2,
                                                     Type par_name3) {
          DoSomething();
          ...
@ -3882,15 +3901,18 @@ Tashana Landray
      <CODE_SNIPPET>
        if (this_one_thing &gt; this_other_thing &amp;&amp;
            a_third_thing == a_fourth_thing &amp;&amp;
-            yet_another &amp; last_one) {
+            yet_another &amp;&amp; last_one) {
          ...
        }
      </CODE_SNIPPET>
      <p>
-        Note that both of the <code>&amp;&amp;</code> logical AND
-        operators are the end of the line.  Feel free to insert extra
-        parentheses judiciously, because they can be very helpful in
-        increasing readability when used appropriately.
+        Note that when the code wraps in this example, both of
+        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,
+        because they can be very helpful in increasing readability
+        when used appropriately.
      </p>
    </BODY>
  </STYLEPOINT>
@ -4166,7 +4188,7 @@ Tashana Landray
        vector&lt;char *&gt; x;           // Spaces between type and pointer are
                                    // okay, but be consistent.
        set&lt;list&lt;string&gt; &gt; x;       // C++ requires a space in &gt; &gt;.
-        set&lt; list&lt;string&gt; &gt; x;      // You may optionally make use
+        set&lt; list&lt;string&gt; &gt; x;      // You may optionally use
                                    // symmetric spacing in &lt; &lt;.
        </CODE_SNIPPET>
      </SUBSECTION>
@ -4377,7 +4399,7 @@ Tashana Landray
 <HR/>

 <p align="right">
-Revision 3.146
+Revision 3.154
 </p>


--- a/pyguide.html
+++ b/pyguide.html
--- a/styleguide.xsl
+++ b/styleguide.xsl
@ -162,7 +162,7 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
  </xsl:template>

  <xsl:template match="CATEGORY">
-    <SPAN>
+    <DIV>
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
      <H2>
        <xsl:variable name="category_name">
@ -175,11 +175,11 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
        <xsl:value-of select="@title"/>
      </H2>
      <xsl:apply-templates/>
-    </SPAN>
+    </DIV>
  </xsl:template>

  <xsl:template match="STYLEPOINT">
-    <SPAN>
+    <DIV>
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
      <xsl:variable name="stylepoint_name">
        <xsl:call-template name="anchorname">
@ -222,23 +222,22 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
      <xsl:apply-templates>
        <xsl:with-param name="anchor_prefix" select="$stylepoint_name" />
      </xsl:apply-templates>
-    </SPAN>
+    </DIV>
  </xsl:template>

  <xsl:template match="SUMMARY">
    <xsl:param name="anchor_prefix" />
-    <SPAN>
+    <DIV style="display:inline;">
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
      <xsl:apply-templates/>
-    </SPAN>
+    </DIV>
  </xsl:template>

  <xsl:template match="BODY">
    <xsl:param name="anchor_prefix" />
-    <SPAN>
+    <DIV>
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
-      <BR/>
-      <SPAN class="stylepoint_body">
+      <DIV class="stylepoint_body">
        <xsl:attribute name="name"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
        <xsl:attribute name="id"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
        <xsl:attribute name="style">
@ -254,8 +253,8 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
          </A>
        </SPAN>
        <xsl:apply-templates/>
-      </SPAN>
-    </SPAN>
+      </DIV>
+    </DIV>
  </xsl:template>

  <xsl:template match="DEFINITION">
@ -293,9 +292,9 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
  <xsl:template match="TODO">
    <P>
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
-      <SPAN style="font-size: 150%;">TODO:
+      <DIV style="font-size: 150%;">TODO:
        <xsl:apply-templates/>
-      </SPAN>
+      </DIV>
    </P>
  </xsl:template>

@ -308,7 +307,7 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
  </xsl:template>

  <xsl:template match="CODE_SNIPPET">
-    <SPAN>
+    <DIV>
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
      <PRE><xsl:call-template name="print_without_leading_chars">
           <xsl:with-param name="text" select="."/>
@ -321,11 +320,11 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
             </xsl:call-template>
           </xsl:with-param>
         </xsl:call-template></PRE>
-    </SPAN>
+    </DIV>
  </xsl:template>

  <xsl:template match="BAD_CODE_SNIPPET">
-    <SPAN>
+    <DIV>
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
      <PRE class="badcode"><xsl:call-template name="print_without_leading_chars">
           <xsl:with-param name="text" select="."/>
@ -338,25 +337,25 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
             </xsl:call-template>
           </xsl:with-param>
         </xsl:call-template></PRE>
-    </SPAN>
+    </DIV>
  </xsl:template>

  <xsl:template match="PY_CODE_SNIPPET">
-    <SPAN>
+    <DIV>
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
      <PRE><xsl:call-template name="print_python_code">
             <xsl:with-param name="text" select="."/>
           </xsl:call-template></PRE>
-    </SPAN>
+    </DIV>
  </xsl:template>

  <xsl:template match="BAD_PY_CODE_SNIPPET">
-    <SPAN>
+    <DIV>
      <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
      <PRE class="badcode"><xsl:call-template name="print_python_code">
                             <xsl:with-param name="text" select="."/>
                           </xsl:call-template></PRE>
-    </SPAN>
+    </DIV>
  </xsl:template>

  <xsl:template match="FUNCTION">