From f7facf90268cee3f4f25f08e49147c782b1185a0 Mon Sep 17 00:00:00 2001
From: mmentovai
-Revision 3.133
+Revision 3.146
- Objects with static storage duration, including global variables, + Objects with static storage duration, including global variables, static variables, static class member variables, and function static - variables, must be Plain Old Data (POD): only ints, chars, floats, and - void, and arrays of/structs of/pointers to POD. Static variables must - not be initialized with the result of a function; and non-const static - variables must not be used in threaded code. + variables, must be Plain Old Data (POD): only ints, chars, floats, or + pointers, or arrays/structs of POD.
- The order in which class constructors, destructors, and initializers for + The order in which class constructors and initializers for static variables are called is only partially specified in C++ and can even change from build to build, which can cause bugs that are difficult - to find. For example, at program-end time a static variable might have + to find. Therefore in addition to banning globals of class type, we do + not allow static POD variables to be initialized with the result of a + function, unless that function (such as getenv(), or getpid()) does not + itself depend on any other globals. +
++ Likewise, the order in which destructors are called is defined to be the + reverse of the order in which the constructors were called. Since + constructor order is indeterminate, so is destructor order. + For example, at program-end time a static variable might have been destroyed, but code still running -- perhaps in another thread -- - tries to access it and fails. + tries to access it and fails. Or the destructor for a static 'string' + variable might be run prior to the destructor for another variable that + contains a reference to that string.
As a result we only allow static variables to contain POD data. This
- rule completely disallows vector
(use C arrays instead),
- string
(use const char*
), or anything that
- contains or points to any class instance in any way, from ever being a
- part of a static variable. For similar reasons, we don't allow static
- variables to be initialized with the result of a function call.
+ rule completely disallows vector
(use C arrays instead), or
+ string
(use const char []
).
If you need a static or global variable of a class type, consider - initializing a pointer which you never free from your main() function - or from pthread_once(). + initializing a pointer (which will never be freed), from either your + main() function or from pthread_once(). Note that this must be a raw + pointer, not a "smart" pointer, since the smart pointer's destructor + will have the order-of-destructor issue that we are trying to avoid.
@@ -792,9 +801,9 @@ Tashana LandrayInit()
method for non-trivial
- initialization.
+ In general, constructors should merely set member variables to their
+ initial values. Any complex initialization should go in an explicit
+ Init()
method.
Init()
method and/or adding a
- member flag that indicates whether the object was successfully
- initialized.
+ having an explicit Init()
method. In particular,
+ constructors should not call virtual functions, attempt to raise
+ errors, access potentially uninitialized global variables, etc.
- If your class defines member variables has no other
+ If your class defines member variables and has no other
constructors you must define a default constructor (one that
takes no arguments). It should preferably initialize the
object in such a way that its internal state is consistent
@@ -933,19 +942,22 @@ Tashana Landray
- Most classes do not need to be copyable, and should not have a
- copy constructor or an assignment operator. Unfortunately, the
- compiler generates these for you, and makes them public, if
- you do not declare them yourself.
+ Few classes need to be copyable. Most should have neither a
+ copy constructor nor an assignment operator. In many situations,
+ a pointer or reference will work just as well as a copied value,
+ with better performance. For example, you can pass function
+ parameters by reference or pointer instead of by value, and you can
+ store pointers rather than objects in an STL container.
- Consider adding dummy declarations for the copy constructor and
- assignment operator in the class'
+ If your class does not need a copy constructor or assignment
+ operator, you must explicitly disable them.
+
+
+ To do so, add dummy declarations for the copy constructor and
+ assignment operator in the
+ For convenience, a
- In almost all cases your class should use the
-
- You may be tempted to make your class copyable so that you
- can use it as a value in STL containers. In almost all such
- cases you should really put pointers to your
- objects in the STL container. You may also want to consider
- using
-
-
Limit the use of
@@ -1256,16 +1267,18 @@ Tashana Landray
Overloading also has surprising ramifications. For instance,
- you can't forward declare classes that overload
-
In general, do not overload operators. The assignment operator
(
However, there may be rare cases where you need to overload
@@ -1296,10 +1309,15 @@ Tashana Landray
@@ -2603,7 +2621,7 @@ Tashana Landray
convention that your
project
- uses.
+ uses. If there is no consistent local pattern to follow, prefer "_".
@@ -2978,8 +2996,8 @@ Tashana Landray
- Every file should have a comment at the top, below the
- and author line, that describes the contents of the file.
+ Every file should have a comment at the top, below the copyright
+ notice and author line, that describes the contents of the file.
Generally a
+ When declaring nested namespaces, put each namespace on its own line.
+
-Revision 3.133
+Revision 3.146
-Revision 2.12
+Revision 2.14
Google has already released open-source code that conforms to these
- guidelines as part of the
+ guidelines as part of the
Google Toolbox for Mac project
@@ -102,13 +102,13 @@ Revision 2.12
Code meant to be shared across different projects is a good candidate to
be included in this repository.
Note that this guide is not an Objective-C tutorial. We assume that the
reader is familiar with the language. If you are new to Objective-C or
- need a refresher, please read
+ need a refresher, please read
The Objective-C Programming Language
.
@@ -117,7 +117,7 @@ Revision 2.12
They say an example is worth a thousand words so let's start off with an
example that should give you a feel for the style, spacing, naming, etc.
@@ -135,9 +135,9 @@ Revision 2.12
// Created by Greg Miller on 6/13/08.
// Copyright 2008 Google, Inc. All rights reserved.
//
-
+
#import <Foundation/Foundation.h>
-
+
// A sample class demonstrating good Objective-C style. All interfaces,
// categories, and protocols (read: all top-level declarations in a header)
// MUST be commented. Comments must also be adjacent to the object they're
@@ -149,32 +149,32 @@ Revision 2.12
NSString *foo_;
NSString *bar_;
}
-
+
// Returns an autoreleased instance of GMFoo. See -initWithString: for details
// about the argument.
+ (id)fooWithString:(NSString *)string;
-
+
// Designated initializer. |string| will be copied and assigned to |foo_|.
- (id)initWithString:(NSString *)string;
-
+
// Gets and sets the string for |foo_|.
- (NSString *)foo;
- (void)setFoo:(NSString *)newFoo;
-
+
// Does some work on |blah| and returns YES if the work was completed
// successfuly, and NO otherwise.
- (BOOL)doWorkWithString:(NSString *)blah;
-
+
@end
-
+
An example source file, demonstating the correct commenting and spacing
for the
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
+ When the first keyword is shorter than the others, indent the later
+ lines by at least four spaces. You can do this by making keywords
+ line up vertically, not aligning colons:
+
+ Or you may align all colons, indenting the first keyword if needed,
+ as below. In editing existing source, use the convention in that
+ file.
+ DISALLOW_COPY_AND_ASSIGN
.
+ Provide a copy constructor and assignment operator only when necessary.
+ Otherwise, disable them with DISALLOW_COPY_AND_ASSIGN
.
CopyFrom()
-style workarounds because they combine
+ construction with copying, the compiler can elide them in some
+ contexts, and they make it easier to avoid heap allocation.
private:
section,
- without providing definitions. With these dummy routines marked
- private, a compilation error will be raised if other code
- attempts to use them. For convenience, a
- DISALLOW_COPY_AND_ASSIGN
macro can be used:
+ If your class needs to be copyable, prefer providing a copy method,
+ such as CopyFrom()
or Clone()
, rather than
+ a copy constructor, because such methods cannot be invoked
+ implicitly. If a copy method is insufficient in your situation
+ (e.g. for performance reasons, or because your class needs to be
+ stored by value in an STL container), provide both a copy
+ constructor and assignment operator.
+ private:
section of your
+ class, but do not provide any corresponding definition (so that
+ any attempt to use them results in a link error).
+ DISALLOW_COPY_AND_ASSIGN
macro
+ can be used:
DISALLOW_COPY_AND_ASSIGN
- macro as described above. If your class is one of the rare
- classes that does need to be copyable, you should document why
- this is so in the header file for that class, and you should
- define the copy constructor and assignment operator
- appropriately. Remember to check for self-assignment in
- operator=
.
- std::tr1::shared_ptr
.
protected
to those member
functions that might need to be accessed from subclasses.
- Note that data members must always
+ Note that data members should
be private.
operator&
.
+ if a class overloads unary operator&
, it
+ cannot safely be forward-declared.
operator=
), in particular, is insidious and
should be avoided. You can define functions like
- Equals()
and CopyFrom()
if you need
- them.
+ Equals()
and CopyFrom()
if you
+ need them. Likewise, avoid the dangerous
+ unary operator&
at all costs, if there's
+ any possibility the class might be forward-declared.
private
, and provide
- access to them through accessor functions as needed. Typically
- a variable would be called foo_
and the accessor
- function foo()
. You may also want a mutator
- function set_foo()
.
+ 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
+
+
+ Google Test). Typically a variable would be
+ called foo_
and the accessor function
+ foo()
. You may also want a mutator function
+ set_foo()
.
.h
file will describe the classes
@@ -4003,7 +4021,7 @@ Tashana Landray
@implementation
of an interface. It also includes the
reference implementations for important methods like getters and setters,
init
, and dealloc
.
:
before the parameter.
@public
and @private
access modifiers
@@ -322,7 +346,7 @@ Revision 2.12
...
}
@end
-
+