StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Update C++ style guide to 3.161:

Browse Source 
- 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.
This commit is contained in:
mmentovai 2010-05-12 16:52:16 +00:00
parent 0518964d22
commit e5aeb8fb72
2 changed files with 107 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
cppguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 3.154 Revision 3.161
</p> </p>
@ -204,6 +204,16 @@ Tashana Landray
include several header files. include several header files.
</p> </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> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -1308,7 +1318,7 @@ Tashana Landray
<STYLEPOINT title="Access Control"> <STYLEPOINT title="Access Control">
<SUMMARY> <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 access to them through accessor functions as needed (for
technical reasons, we allow data members of a test fixture class technical reasons, we allow data members of a test fixture class
to be <code>protected</code> when using to be <code>protected</code> when using
@ -1318,6 +1328,8 @@ Tashana Landray
called <code>foo_</code> and the accessor function called <code>foo_</code> and the accessor function
<code>foo()</code>. You may also want a mutator function <code>foo()</code>. You may also want a mutator function
<code>set_foo()</code>. <code>set_foo()</code>.
Exception: <code>static const</code> data members (typically
called <code>kFoo</code>) need not be <code>private</code>.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -1349,14 +1361,15 @@ Tashana Landray
</p> </p>
<ul> <ul>
<li> Typedefs and Enums</li> <li> Typedefs and Enums</li>
<li> Constants</li> <li> Constants (<code>static const</code> data members)</li>
<li> Constructors</li> <li> Constructors</li>
<li> Destructor</li> <li> Destructor</li>
<li> Methods, including static methods</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> </ul>
<p> <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 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>. should be the last thing in the class. See <a HREF="#Copy_Constructors">Copy Constructors</a>.
</p> </p>
@ -2810,11 +2823,18 @@ Tashana Landray
<SUBSECTION title="Regular Functions"> <SUBSECTION title="Regular Functions">
<p> <p>
Functions should start with a capital letter and have a 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> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
AddTableEntry() AddTableEntry()
DeleteUrl() DeleteUrl()
OpenFileOrDie()
</CODE_SNIPPET> </CODE_SNIPPET>
</SUBSECTION> </SUBSECTION>
@ -3912,7 +3932,10 @@ Tashana Landray
wrapping all operators at the beginning of the line is also 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 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> </p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -4399,7 +4422,7 @@ Tashana Landray
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 3.154 Revision 3.161
</p> </p>

91
objcguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 2.14 Revision 2.18
</p> </p>
@ -292,7 +292,7 @@ Revision 2.14
<p> <p>
If you have too many parameters to fit on one line, giving each its 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 own line is preferred. If multiple lines are used, align each using
the <code>:</code> before the parameter. the colon before the parameter.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
- (void)doSomethingWith:(GTMFoo *)theFoo - (void)doSomethingWith:(GTMFoo *)theFoo
@ -313,17 +313,55 @@ Revision 2.14
... ...
} }
</CODE_SNIPPET> </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> <p>
Or you may align all colons, indenting the first keyword if needed, Invocations should have all arguments on one line:
as below. In editing existing source, use the convention in that
file.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
- (void) short:(GTMFoo *)theFoo [myObject doFooWith:arg1 name:arg2 error:arg3];
longKeyword:(NSRect)theRect </CODE_SNIPPET>
evenLongerKeyword:(float)theInterval { <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> </CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -1065,6 +1103,29 @@ Revision 2.14
</BODY> </BODY>
</STYLEPOINT> </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"> <STYLEPOINT title="Setters copy NSStrings">
<SUMMARY> <SUMMARY>
Setters taking an <code>NSString</code>, should always <code>copy</code> Setters taking an <code>NSString</code>, should always <code>copy</code>
@ -1474,10 +1535,10 @@ Revision 2.14
about the presentation. about the presentation.
</li> </li>
<li> <li>
Use a <code>protocol</code> for callback APIs where all the Define callback APIs with <code>@protocol</code>, using
methods must be implemented. Use a <code>category</code> (or an <code>@optional</code> if not all the methods are required.
"informal protocol") when not all the methods need to be (Exception: when using Objective-C 1.0, <code>@optional</code> isn't
implemented. available, so use a category to define an "informal protocol".)
</li> </li>
</ul> </ul>
</p> </p>
@ -1489,7 +1550,7 @@ Revision 2.14
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 2.14 Revision 2.18
</p> </p>