From b6870cb5db3d6e2edfa0cb2998d2aa4b58b4ac69 Mon Sep 17 00:00:00 2001 From: mmentovai Date: Thu, 5 Aug 2010 00:39:32 +0000 Subject: [PATCH] Update C++ style guide to 3.170: - Allow overloading a function judiciously. - _unittest and _regtest are deprecated. - Document C++0x policy. - Allow namespace aliases in .h files when inside namespaces. - Give examples for and against parentheses with return. - Update set of allowed Boost headers. - Add a caveat to the forward-declaration section, mentioning impicit constructors. --- cppguide.xml | 208 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 150 insertions(+), 58 deletions(-) diff --git a/cppguide.xml b/cppguide.xml index 3df79ea..28b54f5 100644 --- a/cppguide.xml +++ b/cppguide.xml @@ -4,7 +4,7 @@

-Revision 3.161 +Revision 3.170

@@ -148,7 +148,7 @@ Tashana Landray Don't use an #include when a forward declaration - would suffice. + would suffice.

@@ -178,7 +178,13 @@ Tashana Landray Foo&.

  • We can declare (but not define) functions with arguments, - and/or return values, of type Foo. + and/or return values, of type Foo. (One + exception is if an argument Foo + or const Foo& has a + non-explicit, one-argument constructor, + + in which case we need the full definition to support + automatic type conversion.)
  • We can declare static data members of type Foo. This is because static data members @@ -386,7 +392,7 @@ Tashana Landray

    dir/foo.cc and dir2/foo2.h are often in the same - directory (e.g. base/basictypes_unittest.cc and + directory (e.g. base/basictypes_test.cc and base/basictypes.h), but can be in different directories too.

    @@ -581,13 +587,35 @@ Tashana Landray
  • Namespace aliases are allowed anywhere in a - .cc file, and in functions and methods in - .h files. + .cc file, anywhere inside the named + namespace that wraps an entire .h file, + and in functions and methods. - // OK in .cc files. - // Must be in a function or method in .h files. + // Shorten access to some commonly used names in .cc files. namespace fbz = ::foo::bar::baz; + + // Shorten access to some commonly used names (in a .h file). + namespace librarian { + // The following alias is avaliable to all files including + // this header (in namespace librarian): + // alias names should therefore be chosen consistently + // within a project. + namespace pd_s = ::pipeline_diagnostics::sidetable; + + inline void my_inline_function() { + // namespace alias local to a function (or method). + namespace fbz = ::foo::bar::baz; + ... + } + } // namespace librarian +

    + Note that an alias in a .h file is visible to everyone + #including that file, so public headers (those available + outside a project) and headers transitively #included by them, + should avoid defining aliases, as part of the general + goal of keeping public APIs as small as possible. +

    • @@ -1474,7 +1502,7 @@ Tashana Landray

    cpplint.py - is a tool that reads a source file and + 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 @@ -1547,10 +1575,10 @@ Tashana Landray

    - Use overloaded functions (including constructors) only in cases - where input can be specified in different types that contain the - same information. Do not use function overloading to simulate - default function parameters. + Use overloaded functions (including constructors) only if a + reader looking at a call site can get a good idea of what is + happening without having to first figure out exactly which + overload is being called. @@ -1574,20 +1602,18 @@ Tashana Landray convenient for Visitors. - One reason to minimize function overloading is that - overloading can make it hard to tell which function is being - called at a particular call site. Another one is that most - people are confused by the semantics of inheritance if a - deriving class overrides only some of the variants of a - function. Moreover, reading client code of a library may - become unnecessarily hard because of all the reasons against - default function parameters. + If a function is overloaded by the argument types alone, a + reader may have to understand C++'s complex matching rules in + order to tell what's going on. Also many people are confused + by the semantics of inheritance if a derived class overrides + only some of the variants of a function. If you want to overload a function, consider qualifying the name with some information about the arguments, e.g., AppendString(), AppendInt() rather than just Append(). +     @@ -2517,40 +2543,97 @@ Tashana Landray techniques, and an excessively "functional" style of programming. - - In order to maintain a high level of readability for all contributors - who might read and maintain code, we only allow an approved subset of - Boost features. Currently, the following libraries are permitted: - - We are actively considering adding other Boost features to the list, so - this rule may be relaxed in the future. +
    + + In order to maintain a high level of readability for all contributors + who might read and maintain code, we only allow an approved subset of + Boost features. Currently, the following libraries are permitted: +
      +
    • + Call Traits from boost/call_traits.hpp +
      • +
    • + Compressed Pair from boost/compressed_pair.hpp +
      • +
    • + Pointer Container from boost/ptr_container except + serialization and wrappers for containers not in the C++03 + standard (ptr_circular_buffer.hpp and + ptr_unordered*) +
      • +
    • + Array from boost/array.hpp +
      • +
    • + The Boost Graph Library (BGL) from boost/graph, + except serialization (adj_list_serialize.hpp) and + parallel/distributed algorithms and data structures + (boost/graph/parallel/* and + boost/graph/distributed/*). +
      • +
    • + Property Map from boost/property_map, except + parallel/distributed property maps + (boost/property_map/parallel/*). +
      • +
    • The part of + + Iterator that deals with defining iterators: + boost/iterator/iterator_adaptor.hpp, + boost/iterator/iterator_facade.hpp, and + boost/function_output_iterator.hpp
      • +
    + We are actively considering adding other Boost features to the list, so + this rule may be relaxed in the future. +
    +     + + + + + + Use only approved libraries and language extensions from C++0x. + Currently, none are approved. + + + + C++0x is the next ISO C++ standard, currently in + final + committee draft form. It contains + significant + changes both to the language and libraries. + + + We expect that C++0x will become the next standard, and eventually will + be supported by most C++ compilers. It standardizes some common C++ + extensions that we use already, allows shorthands for some operations, + and has some safety improvements. + + +

    + The C++0x standard is substantialy more complex than its predecessor + (1,300 pages versus 800 pages), and is + unfamilar to many developers. The long-term effects of some + features on code readability and maintenance are unknown. We cannot + predict when its various features will be implemented uniformly by + tools that may be of interest (gcc, icc, clang, Eclipse, etc.). +

    +

    + As with Boost, some C++0x extensions encourage + coding practices that hamper readability—for example by removing + checked redundancy (such as type names) that may be helpful to readers, + or by encouraging template metaprogramming. Other extensions + duplicate functionality available through existing + mechanisms, which may lead to + confusion and conversion costs. +

    +     + + Use only C++0x libraries and language features that have been approved + for use. Currently, no such features are approved. + Features will be approved individually as appropriate.     @@ -2665,6 +2748,7 @@ Tashana Landray my_useful_class.cc
    my-useful-class.cc
    myusefulclass.cc
    + myusefulclass_test.cc // _unittest and _regtest are deprecated.

    @@ -2825,7 +2909,7 @@ Tashana Landray Functions should start with a capital letter and have a capital letter for each new word. No underscores.

    -

    +

    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 @@ -3942,15 +4026,23 @@ Tashana Landray

    - Do not surround the return expression with parentheses. + Do not needlessly surround the return expression with + parentheses.

    - Return values should not have parentheses: + Use parentheses in return expr; only where you would use + them in x = expr;.

    - return x; // not return(x); + return result; // No parentheses in the simple case. + return (some_long_condition && // Parentheses ok to make a complex + another_condition); // expression more readable. + + return (value); // You wouldn't write var = (value); + return(result); // return is not a function! + @@ -4422,7 +4514,7 @@ Tashana Landray

    -Revision 3.161 +Revision 3.170