Update C++ style guide to 3.174:

- Add leading blank line exception. - Improve guidance for function definition comments. - Tweak class comment example to not violate type naming guidelines. Update Objective-C style guide to 2.21: - Prohibit +new. Update JavaScript style guide to 2.9: - Add new "Function Declarations Within Blocks" section. - Add new "Internet Explorer's Conditional Comments" section. - Add new "Alias long type names to improve readability" section. - Add @lends.
2024-03-22 13:11:43 +08:00 · 2010-10-04 16:26:53 +00:00 · 2010-10-04 16:26:53 +00:00 · 7ead64485b
commit 7ead64485b
parent b729e3cfe3
3 changed files with 169 additions and 45 deletions
--- a/cppguide.xml
+++ b/cppguide.xml
@ -4,7 +4,7 @@

 <p align="right">

-Revision 3.171
+Revision 3.174
 </p>


@ -3151,12 +3151,12 @@ Tashana Landray
    <BODY>
      <CODE_SNIPPET>
        // Iterates over the contents of a GargantuanTable.  Sample usage:
-        //    GargantuanTable_Iterator* iter = table-&gt;NewIterator();
+        //    GargantuanTableIterator* iter = table-&gt;NewIterator();
        //    for (iter-&gt;Seek("foo"); !iter-&gt;done(); iter-&gt;Next()) {
        //      process(iter-&gt;key(), iter-&gt;value());
        //    }
        //    delete iter;
-        class GargantuanTable_Iterator {
+        class GargantuanTableIterator {
          ...
        };
      </CODE_SNIPPET>
@ -3260,7 +3260,7 @@ Tashana Landray
      <SUBSECTION title="Function Definitions">
        <p>
          Each function definition should have a comment describing
-          what the function does and anything tricky about how it does
+          what the function does if there's anything tricky about how it does
          its job.  For example, in the definition comment you might
          describe any coding tricks you use, give an overview of the
          steps you go through, or explain why you chose to implement
@ -4356,9 +4356,10 @@ Tashana Landray
      <p>
        This is more a principle than a rule: don't use blank lines
        when you don't have to.  In particular, don't put more than
-        one or two blank lines between functions, don't start or end
-        functions with a blank line, and be discriminating with your
-        use of blank lines inside functions.
+        one or two blank lines between functions, resist starting
+        functions with a blank line, don't end functions with a blank
+        line, and be discriminating with your use of blank lines
+        inside functions.
      </p>
      <p>
        The basic principle is: The more code that fits on one screen,
@ -4369,39 +4370,16 @@ Tashana Landray
        whitespace.
      </p>
      <p>
-        Don't start or end functions with blank lines:
-        <BAD_CODE_SNIPPET>
-          void Function() {
-
-            // Unnecessary blank lines before and after
-
-          }
-        </BAD_CODE_SNIPPET>
-      </p>
-      <p>
-        Don't start and end blocks with blank lines either:
-        <BAD_CODE_SNIPPET>
-          while (condition) {
-            // Unnecessary blank line after
-
-          }
-          if (condition) {
-
-            // Unnecessary blank line before
-          }
-        </BAD_CODE_SNIPPET>
-        However, it's okay to add blank lines between a chain of
-        if-else blocks:
-        <CODE_SNIPPET>
-        if (condition) {
-          // Some lines of code too small to move to another function,
-          // followed by a blank line.
-
-        } else {
-          // Another block of code
-        }
-        </CODE_SNIPPET>
+        Some rules of thumb to help when blank lines may be useful:
      </p>
+      <ul>
+        <li> Blank lines at the beginning or end of a function very
+             rarely help readability.
+             </li>
+        <li> Blank lines inside a chain of if-else blocks may well
+             help readability.
+             </li>
+      </ul>
    </BODY>
  </STYLEPOINT>
 </CATEGORY>
@ -4551,7 +4529,7 @@ Tashana Landray
 <HR/>

 <p align="right">
-Revision 3.171
+Revision 3.174
 </p>


--- a/javascriptguide.xml
+++ b/javascriptguide.xml
@ -3,7 +3,7 @@
 <GUIDE title="Google JavaScript Style Guide">
  <p class="revision">
    
-    Revision 2.3
+    Revision 2.9
  </p>
  
  <address>
@ -173,6 +173,32 @@
      </BODY>
    </STYLEPOINT>

+    <STYLEPOINT title="Function Declarations Within Blocks">
+      <SUMMARY>No</SUMMARY>
+      <BODY>
+        <p>Do not do this:</p>
+        <BAD_CODE_SNIPPET>
+          if (x) {
+            function foo() {}
+          }
+        </BAD_CODE_SNIPPET>
+
+        <p>While most script engines support Function Declarations within blocks
+          it is not part of ECMAScript (see
+          <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMA-262</a>,
+          clause 13 and 14). Worse implementations are inconsistent with each
+          other and with future EcmaScript proposals. ECMAScript only allows for
+          Function Declarations in the root statement list of a script or
+          function. Instead use a variable initialized with a Function
+          Expression to define a function within a block:</p>
+        <CODE_SNIPPET>
+           if (x) {
+             var foo = function() {}
+           }
+        </CODE_SNIPPET>
+      </BODY>
+    </STYLEPOINT>
+
    <STYLEPOINT title="Exceptions">
      <SUMMARY>Yes</SUMMARY>
      <BODY>
@ -548,6 +574,20 @@
          avoided.</p>
      </BODY>
    </STYLEPOINT>
+
+    <STYLEPOINT title="Internet Explorer's Conditional Comments">
+      <SUMMARY>No</SUMMARY>
+      <BODY>
+        <p>Don't do this:</p>
+        <CODE_SNIPPET>
+        var f = function () {
+            /*@cc_on if (@_jscript) { return 2* @*/  3; /*@ } @*/
+        };
+        </CODE_SNIPPET>
+        <p>Conditional Comments hinder automated tools as they can vary the
+        JavaScript syntax tree at runtime.</p>
+      </BODY>
+    </STYLEPOINT>
  </CATEGORY>

  <CATEGORY title="JavaScript Style Rules">
@ -683,6 +723,65 @@
            
            
          </SUBSUBSECTION>
+          <SUBSUBSECTION title="Alias long type names to improve readability">
+            <p>Use local aliases for fully-qualified types if doing so improves
+              readability. The name of a local alias should match the last part
+              of the type.</p>
+            <CODE_SNIPPET>
+              /**
+               * @constructor
+               */
+              some.long.namespace.MyClass = function() {
+              };
+
+              /**
+               * @param {some.long.namespace.MyClass} a
+               */
+              some.long.namespace.MyClass.staticHelper = function(a) {
+                ...
+              };
+
+              myapp.main = function() {
+                var MyClass = some.long.namespace.MyClass;
+                var staticHelper = some.long.namespace.MyClass.staticHelper;
+                staticHelper(new MyClass());
+              };
+            </CODE_SNIPPET>
+            <p>Do not alias namespaces.</p>
+            <BAD_CODE_SNIPPET>
+              myapp.main = function() {
+                var namespace = some.long.namespace;
+                namespace.MyClass.staticHelper(new namespace.MyClass());
+              };
+            </BAD_CODE_SNIPPET>
+            <p>Avoid accessing properties of an aliased type, unless it is an
+              enum.</p>
+            <CODE_SNIPPET>
+              /** @enum {string} */
+              some.long.namespace.Fruit = {
+                APPLE: 'a',
+                BANANA: 'b'
+              };
+
+              myapp.main = function() {
+                var Fruit = some.long.namespace.Fruit;
+                switch (fruit) {
+                  case Fruit.APPLE:
+                    ...
+                  case Fruit.BANANA:
+                    ...
+                }
+              };
+            </CODE_SNIPPET>
+            <BAD_CODE_SNIPPET>
+              myapp.main = function() {
+                var MyClass = some.long.namespace.MyClass;
+                MyClass.staticHelper(null);
+              };
+            </BAD_CODE_SNIPPET>
+            <p>Never create aliases in the global scope. Use them only in
+              function blocks.</p>
+          </SUBSUBSECTION>
        </SUBSECTION>
        <SUBSECTION title="Filenames">
          <p>Filenames should be all lowercase in order to avoid confusion on
@ -2220,6 +2319,38 @@
                </td>
              </tr>

+              <tr>
+                <td><a name="tag-lends">@lends</a></td>
+                <td>
+                  <tt>@lends objectName</tt><br/>
+                  <tt>@lends {objectName}</tt>
+                  <p><i>For example:</i></p>
+                  <CODE_SNIPPET>
+                    goog.object.extend(
+                        Button.prototype,
+                        /** @lends {Button.prototype} */ {
+                          isButton: function() { return true; }
+                        });
+                  </CODE_SNIPPET>
+                </td>
+                <td>
+                  Indicates that the keys of an object literal should
+                  be treated as properties of some other object. This annotation
+                  should only appear on object literals.<p/>
+
+                  Notice that the name in braces is not a type name like
+                  in other annotations. It's an object name. It names
+                  the object on which the properties are "lent".
+                  For example, <tt>@type {Foo}</tt> means "an instance of Foo",
+                  but <tt>@lends {Foo}</tt> means "the constructor Foo".<p/>
+
+                  The <a href="http://code.google.com/p/jsdoc-toolkit/wiki/TagLends">
+                  JSDoc Toolkit docs</a> have more information on this
+                  annotation.
+                </td>
+                <td>Yes</td>
+              </tr>
+
              <tr>
                <td><a name="tag-private">@private</a></td>
                <td>
@ -2674,7 +2805,6 @@
              <li>@function</li>
              <li>@ignore</li>
              <li>@inner</li>
-              <li>@lends</li>
              <li>@link</li>
              <li>@memberOf</li>
              <li>@name</li>
@ -3021,7 +3151,7 @@
  </PARTING_WORDS>

  <p align="right">
-    Revision 2.3
+    Revision 2.9
  </p>

  
--- a/objcguide.xml
+++ b/objcguide.xml
@ -4,7 +4,7 @@

 <p align="right">

-Revision 2.20
+Revision 2.21
 </p>


@ -932,6 +932,22 @@ Revision 2.20
    </BODY>
  </STYLEPOINT>

+  <STYLEPOINT title="Avoid +new">
+    <SUMMARY>
+      Do not invoke the <code>NSObject</code> class method <code>new</code>,
+      nor override it in a subclass. Instead, use <code>alloc</code> and
+      <code>init</code> methods to instantiate retained objects.
+    </SUMMARY>
+    <BODY>
+      <p>
+        Modern Objective-C code explicitly calls <code>alloc</code> and an
+        <code>init</code> method to create and retain an object.  As the
+        <code>new</code> class method is rarely used, it makes reviewing code
+        for correct memory management more difficult.
+      </p>
+    </BODY>
+  </STYLEPOINT>
+
  <STYLEPOINT title="Keep the Public API Simple">
    <SUMMARY>
      Keep your class simple; avoid "kitchen-sink" APIs. If a method doesn't
@ -1556,7 +1572,7 @@ Revision 2.20
 <HR/>

 <p align="right">
-Revision 2.20
+Revision 2.21
 </p>