From e5aeb8fb72cf3e2dc237fe0e40f70813e3fc321b Mon Sep 17 00:00:00 2001 From: mmentovai Date: Wed, 12 May 2010 16:52:16 +0000 Subject: [PATCH] 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. --- cppguide.xml | 39 +++++++++++++++++----- objcguide.xml | 91 ++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 107 insertions(+), 23 deletions(-) diff --git a/cppguide.xml b/cppguide.xml index c61416f..3df79ea 100644 --- a/cppguide.xml +++ b/cppguide.xml @@ -4,7 +4,7 @@

-Revision 3.154 +Revision 3.161

@@ -204,6 +204,16 @@ Tashana Landray include several header files.

+ + If you use a symbol Foo in your source file, you + should bring in a definition for Foo 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 Foo + is used in myfile.cc, it's ok to #include (or + forward-declare) Foo in myfile.h, + instead of myfile.cc. + @@ -1308,7 +1318,7 @@ Tashana Landray - Make all data members private, and provide + Make data members private, and provide access to them through accessor functions as needed (for technical reasons, we allow data members of a test fixture class to be protected when using @@ -1318,6 +1328,8 @@ Tashana Landray called foo_ and the accessor function foo(). You may also want a mutator function set_foo(). + Exception: static const data members (typically + called kFoo) need not be private.

@@ -1349,14 +1361,15 @@ Tashana Landray

- The DISALLOW_COPY_AND_ASSIGN macro invocation + Friend declarations should always be in the private section, and + the DISALLOW_COPY_AND_ASSIGN macro invocation should be at the end of the private: section. It should be the last thing in the class. See Copy Constructors.

@@ -2810,11 +2823,18 @@ Tashana Landray

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. +

+

+ 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.

AddTableEntry() DeleteUrl() + OpenFileOrDie() @@ -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 && and + ~, rather than the word operators, such as and + and compl.

@@ -4399,7 +4422,7 @@ Tashana Landray

-Revision 3.154 +Revision 3.161

diff --git a/objcguide.xml b/objcguide.xml index 0ffb3dd..6881a4a 100644 --- a/objcguide.xml +++ b/objcguide.xml @@ -4,7 +4,7 @@

-Revision 2.14 +Revision 2.18

@@ -292,7 +292,7 @@ Revision 2.14

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 : before the parameter. + the colon before the parameter.

- (void)doSomethingWith:(GTMFoo *)theFoo @@ -313,17 +313,55 @@ Revision 2.14 ... } + + + + + + 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. + +

- 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:

- - (void) short:(GTMFoo *)theFoo - longKeyword:(NSRect)theRect - evenLongerKeyword:(float)theInterval { - ... - } + [myObject doFooWith:arg1 name:arg2 error:arg3]; + +

+ or have one argument per line, with colons aligned: +

+ + [myObject doFooWith:arg1 + name:arg2 + error:arg3]; + +

+ Don't use any of these styles: +

+ + [myObject doFooWith:arg1 name:arg2 // some lines with >1 arg + error:arg3]; + + [myObject doFooWith:arg1 + name:arg2 error:arg3]; + + [myObject doFooWith:arg1 + name:arg2 // aligning keywords instead of colons + error:arg3]; + + +

+ 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. +

+ + [myObj short:arg1 + longKeyword:arg2 + evenLongerKeyword:arg3]; @@ -1065,6 +1103,29 @@ Revision 2.14 + + + dealloc should process instance variables in the same order + the @interface declares them, so it is easier for a reviewer + to verify. + + +

+ A code reviewer checking a new or revised dealloc + implementation needs to make sure that every retained instance + variable gets released. +

+

+ To simplify reviewing dealloc, order the code so that + the retained instance variables get released in the same order that + they are declared in the @interface. If + dealloc invokes other methods that release instance + variables, add comments describing what instance variables those + methods handle. +

+ + + Setters taking an NSString, should always copy @@ -1474,10 +1535,10 @@ Revision 2.14 about the presentation.
  • - Use a protocol for callback APIs where all the - methods must be implemented. Use a category (or an - "informal protocol") when not all the methods need to be - implemented. + Define callback APIs with @protocol, using + @optional if not all the methods are required. + (Exception: when using Objective-C 1.0, @optional isn't + available, so use a category to define an "informal protocol".)

    • @@ -1489,7 +1550,7 @@ Revision 2.14

    -Revision 2.14 +Revision 2.18