-Revision 3.127 +Revision 3.133
@@ -146,8 +146,8 @@ Tashana Landray#include in .h files.
+ Don't use an #include when a forward declaration
+ would suffice.
@@ -462,8 +462,8 @@ Tashana Landray namespace { // This is in a .cc file. // The content of a namespace is not indented - enum { UNUSED, EOF, ERROR }; // Commonly used tokens. - bool AtEof() { return pos_ == EOF; } // Uses our namespace's EOF. + enum { kUnused, kEOF, kError }; // Commonly used tokens. + bool AtEof() { return pos_ == kEOF; } // Uses our namespace's EOF. } // namespace @@ -742,52 +742,42 @@ Tashana Landray
const
- globals are forbidden in threaded code. Global variables should
- never be initialized with the return value of a function.
+ Static or global variables of class type are forbidden: they cause
+ hard-to-find bugs due to indeterminate order of construction and
+ destruction.
- Unfortunately the order in which constructors, destructors, - and initializers for global variables are called is only - partially specified and can change from build to build. This - can cause bugs that are very difficult to find. + 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.
- Therefore we forbid global variables of class types (which - includes STL string, vector, etc.) because initialization - order might matter for their constructor, now or in the - future. Built-in types and structs of built-in types without - constructors are okay. - - If you need a global variable of a class - type, use the - singleton - pattern. + The order in which class constructors, destructors, 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 + been destroyed, but code still running -- perhaps in another thread -- + tries to access it and fails.
- For global string constants, use C style strings, not
- STL strings:
+ 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.
- Although we permit global variables in the global scope,
- please be judicious in your use of them. Most global variables
- should either be static data members of some class, or, if only
- needed in one .cc file, defined in an unnamed
- namespace. (As an alternative to using
- an unnamed namespace, you can use static linkage to
- limit the variable's scope.)
-
- Please note that static class member variables
- count as global variables, and should not be of class types!
+ 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().
cpplint.py to detect style errors.
+ Use
+ cpplint.py
+ to detect style errors.
- cpplint.py is a tool that reads a source file and
+ cpplint.py
+ is a tool that reads a source file and
identifies many style errors. It is not perfect, and has both false
positives and false negatives, but it is still a valuable tool. False
- positives can be ignored by putting // NOLINT at the end
- of the line.
+ positives can be ignored by putting // NOLINT at
+ the end of the line.
Some projects have instructions on how to run cpplint.py
from their project tools. If the project you are contributing to does
@@ -1501,7 +1494,7 @@ Tashana Landray
void Foo(const string &in, string *out);
- In fact it is a very strong convention that input
+ In fact it is a very strong convention in Google code that input
arguments are values or const references while
output arguments are pointers. Input parameters may be
const pointers, but we never allow
@@ -1948,7 +1941,7 @@ Tashana Landray
Some say printf formatting is ugly and hard to
- read, but streams are often no better. Consider the following
+ read, but streams are often no better. Consider the following
two fragments, both with the same typo. Which is easier to
discover?
const) before the "noun" (int).
- That said, while we encourage putting const first,
+ That said, while we encourage putting const first,
we do not require it. But be consistent with the code around
you!
Type and variable names should typically be nouns: e.g.,
- FileOpener,
+ FileOpener,
num_errors.
MY_EXCITING_ENUM_VALUE.
+ Enumerators should be named either like
+ constants or like
+ macros: either kEnumName
+ or ENUM_NAME.
- The individual enumerators should be all uppercase. The
- enumeration name, UrlTableErrors, is a type, and
+ Preferably, the individual enumerators should be named like
+ constants. However, it is also
+ acceptable to name them like macros. The enumeration name,
+ UrlTableErrors (and
+ AlternateUrlTableErrors), is a type, and
therefore mixed case.
+ Until January 2009, the style was to name enum values like + macros. This caused problems with + name collisions between enum values and macros. Hence, the + change to prefer constant-style naming was put in place. New + code should prefer constant-style naming if possible. + However, there is no reason to change old code to use + constant-style names, unless the old names are actually + causing a compile-time problem. +
+-Revision 3.127 +Revision 3.133
diff --git a/objcguide.xml b/objcguide.xml index 6e15bcc..61af2f3 100644 --- a/objcguide.xml +++ b/objcguide.xml @@ -2,6 +2,11 @@+ +Revision 2.11 +
+#import Objective-C/Objective-C++ headers, and
+ #include C/C++ headers.
+
+ Choose between #import and #include based
+ on the language of the header that you are including.
+
#import.#include. The header should provide its own #define
+ guard.
+ Some Objective-C headers lack #define guards, and expect
+ to be included only by #import. As Objective-C headers
+ may only be included in Objective-C source files and other Objective-C
+ headers, using #import across the board is appropriate.
+
+ Standard C and C++ headers without any Objective-C in them can expect
+ to be included by ordinary C and C++ files. Since there is no
+ #import in standard C or C++, such files will be
+ included by #include in those cases. Using
+ #include for them in Objective-C source files as well
+ means that these headers will always be included with the same
+ semantics.
+
+ This rule helps avoid inadvertent errors in cross-platform
+ projects. A Mac developer introducing a new C or C++ header might
+ forget to add #define guards, which would not cause
+ problems on the Mac if the new header were included with
+ #import, but would break builds on other platforms
+ where #include is used. Being consistent by using
+ #include on all platforms means that compilation is
+ more likely to succeed everywhere or fail everywhere, and avoids
+ the frustration of files working only on some platforms.
+
#import rather than
- #include.
+ #include for Objective-C frameworks.
+Revision 2.11 +
+ diff --git a/styleguide.xsl b/styleguide.xsl index 0345413..f5066db 100644 --- a/styleguide.xsl +++ b/styleguide.xsl @@ -3,7 +3,8 @@ xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcq="http://purl.org/dc/qualifiers/1.0/" -xmlns:fo="http://www.w3.org/1999/XSL/Format"> +xmlns:fo="http://www.w3.org/1999/XSL/Format" +xmlns:fn="http://www.w3.org/2005/xpath-functions">