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

91
objcguide.xml
View File

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