From 71619d34e33cc088c561945772286a2fd4fa8f22 Mon Sep 17 00:00:00 2001 From: mmentovai Date: Wed, 25 Mar 2009 22:24:14 +0000 Subject: [PATCH] Update C++ style guide to 3.133: - Clarify that a "very strong convention" is, in fact, only very strong within Google code - Update the style guide with an additional naming possibility for enums: kEnumName - Reword the summary for the section on header file dependencies - Simplify wording regarding static variables Update Objective-C style guide to 2.11: - Provide guidance on when to use #import and #include - Display revision in style guide Update styleguide.xsl with a hint of things to come Set svn:eol-style on xmlstyle.html --- cppguide.xml | 126 +++++++++------- objcguide.xml | 66 +++++++- styleguide.xsl | 400 +++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 521 insertions(+), 71 deletions(-) diff --git a/cppguide.xml b/cppguide.xml index ab83f63..7840cf2 100644 --- a/cppguide.xml +++ b/cppguide.xml @@ -4,7 +4,7 @@

-Revision 3.127 +Revision 3.133

@@ -146,8 +146,8 @@ Tashana Landray - Use forward declarations to minimize use of - #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 - +

- Global variables of class types are forbidden. Global variables - of built-in types are allowed, although non-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.

- - const char kFrogSays[] = "ribbet"; -

- 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().

@@ -1444,19 +1434,22 @@ Tashana Landray - - Use 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?

@@ -2104,7 +2097,7 @@ Tashana Landray (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!

@@ -2560,7 +2553,7 @@ Tashana Landray

Type and variable names should typically be nouns: e.g., - FileOpener, + FileOpener, num_errors.

@@ -2832,22 +2825,43 @@ Tashana Landray - Enumerators should be all uppercase with underscores between - words: 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.

enum UrlTableErrors { + kOK = 0, + kErrorOutOfMemory, + kErrorMalformedInput, + }; + enum AlternateUrlTableErrors { OK = 0, - ERROR_OUT_OF_MEMORY, - ERROR_MALFORMED_INPUT, + OUT_OF_MEMORY = 1, + MALFORMED_INPUT = 2, }; +

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

+ @@ -4338,7 +4352,7 @@ Tashana Landray

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

+
@@ -444,7 +449,7 @@ }; // file: mac_implementation.mm - #import "cross_platform_header.h" + #include "cross_platform_header.h" // A typical Objective-C class, using Objective-C naming. @interface MyDelegate : NSObject { @@ -904,7 +909,58 @@

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

+
    +
  • When including a header that uses Objective-C or Objective-C++, + use #import.
    • +
  • When including a standard C or C++ header, use + #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 <Cocoa/Cocoa.h> + #include <CoreFoundation/CoreFoundation.h> + #import "GTMFoo.h" + #include "base/basictypes.h" + + + @@ -917,7 +973,7 @@ compiler if you include the top-level root framework. The root framework is generally pre-compiled and can be loaded much more quickly. In addition, remember to use #import rather than - #include. + #include for Objective-C frameworks.

#import <Foundation/Foundation.h> // good @@ -1372,6 +1428,10 @@
+

+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"> @@ -30,13 +31,23 @@ xmlns:fo="http://www.w3.org/1999/XSL/Format">