Update C++ style guide to 3.161:

- Forbid the use of operator synonyms such as "and." - Specify the naming convention (OrDie) to use when a function has crash-on-failure semantics. - Allow static const data members to be non-private. - Specify placement of friend declarations. - Require each file to include headers that they use. Update Objective-C style guide to 2.18: - Prefer @optional to informal protocols when possible. - Specify formatting for invoking methods. - Require that -dealloc be easy to review.
2010-05-12 16:52:16 +00:00 · 2010-05-12 16:52:16 +00:00 · e5aeb8fb72
parent 0518964d22
commit e5aeb8fb72
2 changed files with 107 additions and 23 deletions
--- a/cppguide.xml
+++ b/cppguide.xml
@ -4,7 +4,7 @@

 <p align="right">

-Revision 3.154
+Revision 3.161
 </p>


@ -204,6 +204,16 @@ Tashana Landray
        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,
+        either via an #include or via a forward declaration.  Do not
+        depend on the symbol being brought in transitively via headers
+        not directly included.  One exception is if <code>Foo</code>
+        is used in <code>myfile.cc</code>, it's ok to #include (or
+        forward-declare) <code>Foo</code> in <code>myfile.h</code>,
+        instead of <code>myfile.cc</code>.
+      </SUBSECTION>
    </BODY>
  </STYLEPOINT>

@ -1308,7 +1318,7 @@ Tashana Landray

  <STYLEPOINT title="Access Control">
    <SUMMARY>
-      Make <em>all</em> data members <code>private</code>, and provide
+      Make data members <code>private</code>, and provide
      access to them through accessor functions as needed (for
      technical reasons, we allow data members of a test fixture class
      to be <code>protected</code> when using
@ -1318,6 +1328,8 @@ Tashana Landray
      called <code>foo_</code> and the accessor function
      <code>foo()</code>.  You may also want a mutator function
      <code>set_foo()</code>.
+      Exception: <code>static const</code> data members (typically
+      called <code>kFoo</code>) need not be <code>private</code>.
    </SUMMARY>
    <BODY>
      <p>
@ -1349,14 +1361,15 @@ Tashana Landray
      </p>
      <ul>
        <li> Typedefs and Enums</li>
-        <li> Constants</li>
+        <li> Constants (<code>static const</code> data members)</li>
        <li> Constructors</li>
        <li> Destructor</li>
        <li> Methods, including static methods</li>
-        <li> Data Members, including static data members</li>
+        <li> Data Members (except <code>static const</code> data members)</li>
      </ul>
      <p>
-        The <code>DISALLOW_COPY_AND_ASSIGN</code> macro invocation
+        Friend declarations should always be in the private section, and
+        the <code>DISALLOW_COPY_AND_ASSIGN</code> macro invocation
        should be at the end of the <code>private:</code> section. It
        should be the last thing in the class. See <a HREF="#Copy_Constructors">Copy Constructors</a>.
      </p>
@ -2810,11 +2823,18 @@ Tashana Landray
      <SUBSECTION title="Regular Functions">
        <p>
          Functions should start with a capital letter and have a
-          capital letter for each new word. No underscores:
+          capital letter for each new word. No underscores.
+        </p>
+        <p> 
+          If your function crashes upon an error, you should append OrDie to
+          the function name. This only applies to functions which could be
+          used by production code and to errors that are reasonably
+          likely to occur during normal operation.
        </p>
        <CODE_SNIPPET>
          AddTableEntry()
          DeleteUrl()
+          OpenFileOrDie()
        </CODE_SNIPPET>
      </SUBSECTION>

@ -3912,7 +3932,10 @@ Tashana Landray
        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.
+        when used appropriately.  Also note that you should always use the
+        punctuation operators, such as <code>&amp;&amp;</code> and
+        <code>~</code>, rather than the word operators, such as <code>and</code>
+        and <code>compl</code>.
      </p>
    </BODY>
  </STYLEPOINT>
@ -4399,7 +4422,7 @@ Tashana Landray
 <HR/>

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


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

 <p align="right">

-Revision 2.14
+Revision 2.18
 </p>


@ -292,7 +292,7 @@ Revision 2.14
      <p>
        If you have too many parameters to fit on one line, giving each its
        own line is preferred. If multiple lines are used, align each using
-        the <code>:</code> before the parameter.
+        the colon before the parameter.
      </p>
      <CODE_SNIPPET>
        - (void)doSomethingWith:(GTMFoo *)theFoo
@ -313,17 +313,55 @@ Revision 2.14
          ...
        }
      </CODE_SNIPPET>
+    </BODY>
+  </STYLEPOINT>
+
+  <STYLEPOINT title="Method Invocations">
+    <SUMMARY>
+      Method invocations should be formatted much like method declarations.
+      When there's a choice of formatting styles, follow the convention
+      already used in a given source file.
+    </SUMMARY>
+    <BODY>
      <p>
-        Or you may align all colons, indenting the first keyword if needed,
-        as below. In editing existing source, use the convention in that
-        file.
+        Invocations should have all arguments on one line:
      </p>
      <CODE_SNIPPET>
-        - (void)        short:(GTMFoo *)theFoo
-                  longKeyword:(NSRect)theRect
-            evenLongerKeyword:(float)theInterval {
-          ...
-        }
+        [myObject doFooWith:arg1 name:arg2 error:arg3];
+      </CODE_SNIPPET>
+      <p>
+        or have one argument per line, with colons aligned:
+      </p>
+      <CODE_SNIPPET>
+        [myObject doFooWith:arg1
+                       name:arg2
+                      error:arg3];
+      </CODE_SNIPPET>
+      <p>
+        Don't use any of these styles:
+      </p>
+      <BAD_CODE_SNIPPET>
+        [myObject doFooWith:arg1 name:arg2  // some lines with &gt;1 arg
+                      error:arg3];
+
+        [myObject doFooWith:arg1
+                       name:arg2 error:arg3];
+
+        [myObject doFooWith:arg1
+                  name:arg2  // aligning keywords instead of colons
+                  error:arg3];
+      </BAD_CODE_SNIPPET>
+
+      <p>
+        As with declarations and definitions, when the keyword lengths make
+        it impossible to align colons and still have four leading
+        spaces, indent later lines by four spaces and align keywords after the
+        first one, instead of aligning the colons.
+      </p>
+      <CODE_SNIPPET>
+        [myObj short:arg1
+            longKeyword:arg2
+            evenLongerKeyword:arg3];
      </CODE_SNIPPET>
    </BODY>
  </STYLEPOINT>
@ -1065,6 +1103,29 @@ Revision 2.14
    </BODY>
  </STYLEPOINT>

+  <STYLEPOINT title="dealloc should process instance variables in declaration                      order">
+    <SUMMARY>
+      <code>dealloc</code> should process instance variables in the same order
+      the <code>@interface</code> declares them, so it is easier for a reviewer
+      to verify.
+    </SUMMARY>
+    <BODY>
+      <p>
+        A code reviewer checking a new or revised <code>dealloc</code>
+        implementation needs to make sure that every retained instance
+        variable gets released.
+      </p>
+      <p>
+        To simplify reviewing <code>dealloc</code>, order the code so that
+        the retained instance variables get released in the same order that
+        they are declared in the <code>@interface</code>. If
+        <code>dealloc</code> invokes other methods that release instance
+        variables, add comments describing what instance variables those
+        methods handle.
+      </p>
+    </BODY>
+  </STYLEPOINT>
+
  <STYLEPOINT title="Setters copy NSStrings">
    <SUMMARY>
      Setters taking an <code>NSString</code>, should always <code>copy</code>
@ -1474,10 +1535,10 @@ Revision 2.14
            about the presentation.
          </li>
          <li>
-            Use a <code>protocol</code> for callback APIs where all the
-            methods must be implemented. Use a <code>category</code> (or an
-            "informal protocol") when not all the methods need to be
-            implemented.
+            Define callback APIs with <code>@protocol</code>, using
+            <code>@optional</code> if not all the methods are required.
+            (Exception: when using Objective-C 1.0, <code>@optional</code> isn't
+            available, so use a category to define an "informal protocol".)
          </li>
        </ul>
      </p>
@ -1489,7 +1550,7 @@ Revision 2.14
 <HR/>

 <p align="right">
-Revision 2.14
+Revision 2.18
 </p>