@@ -1849,7 +1849,10 @@ <h3 id="Declaration_Order">Declaration Order</h3>
18491849
18501850< p > Within each section, generally prefer grouping similar
18511851kinds of declarations together, and generally prefer the
1852- following order: types (including < code > typedef</ code > ,
1852+ following order:
1853+ < span class ="drake "> DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN or
1854+ DRAKE_NO_COPY_NO_MOVE_NO_ASSIGN</ span > ,
1855+ types (including < code > typedef</ code > ,
18531856< code > using</ code > , and nested structs and classes),
18541857constants, factory functions, constructors and assignment
18551858operators, destructor, all other methods, data members.</ p >
@@ -2642,28 +2645,41 @@ <h3 id="Friends">Friends</h3>
26422645
26432646< h3 id ="Exceptions "> Exceptions</ h3 >
26442647
2645- < p class ="drake "> Throwing exceptions is permitted and encouraged for error handling only.</ p >
26462648< p class ="nondrake "> We do not use C++ exceptions.</ p >
2649+ < p class ="drake "> Throwing exceptions is permitted and encouraged for error
2650+ reporting only. Catching exceptions is forbidden except in unit tests as
2651+ noted below.</ p >
26472652
26482653< div class ="stylebody ">
26492654 < p class ="drake "> Unit tests may catch exceptions using
26502655 < a href ="https://github.com/google/googletest/blob/master/googletest/docs/AdvancedGuide.md#exception-assertions "> EXPECT_THROW</ a >
2651- if the exception is documented in the API. Otherwise, catching exceptions is
2652- forbidden. For more context, see
2653- < a href ="https://github.com/robotlocomotion/drake/pull/3759 "> PR
2654- #3759</ a > .</ p >
2655-
2656- < p class ="drake "> We allow exceptions to be thrown because it enables a more
2657- detailed description of the error to be provided relative to an assert
2658- statement.</ p >
2659-
2660- < p class ="drake "> Note: This is a work-in-progress rule, but captures our
2661- currently-in-effect style. We are open to discussion on additional uses for
2662- exceptions if and when the need arises.</ p >
2656+ or
2657+ < a href ="https://github.com/RobotLocomotion/drake/blob/master/common/test_utilities/expect_throws_message.h "> DRAKE_EXPECT_THROWS_MESSAGE</ a > ,
2658+ but only if the tested function's Doxygen documentation mentions that the
2659+ function throws an exception.</ p >
2660+
2661+ < p class ="drake "> When documenting exceptions in an API, only state that
2662+ the function will throw < code > std::exception</ code > ; never promise a more
2663+ specific subclass:</ p >
2664+ < ul class ="drake ">
2665+ < li > As we evolve implementations, sometimes it becomes difficult to upkeep
2666+ the old promises (especially if they were the semantically "wrong" type), or
2667+ to refactor the code in ways that keeps the subclass unchanged.</ li >
2668+ < li > There's no great way to deprecate a particular exception signature.</ li >
2669+ < li > Since we can't catch exceptions anyway, nevermind use a multi-layer-catch
2670+ by specific subclasses, the only purpose of a subclass is for improved error
2671+ reporting -- this purpose is still met by throwing a subclass, but we don't
2672+ need to document it in Doxygen for this purpose.</ li >
2673+ </ ul >
2674+ </ p >
26632675</ div >
26642676
26652677< p class ="pros "> </ p >
26662678< ul >
2679+ < li class ="drake "> We allow exceptions to be thrown because it enables a more
2680+ detailed description of the error to be provided relative to an assert
2681+ statement.</ li >
2682+
26672683 < li > Exceptions allow higher levels of an application to
26682684 decide how to handle "can't happen" failures in deeply
26692685 nested functions, without the obscuring and error-prone
@@ -4227,8 +4243,14 @@ <h3 id="Template_metaprogramming">Template Metaprogramming</h3>
42274243
42284244< h3 id ="Boost "> Boost</ h3 >
42294245
4246+ < div class ="drake ">
4247+ < p > Drake's library code is not permitted to use Boost.</ p >
4248+ </ div >
4249+
4250+ < div class ="nondrake ">
42304251< p > Use only approved libraries from the Boost library
42314252collection.</ p >
4253+ </ div >
42324254
42334255< p class ="definition "> </ p >
42344256< p > The
@@ -4249,8 +4271,14 @@ <h3 id="Boost">Boost</h3>
42494271
42504272< p class ="decision "> </ p >
42514273
4274+ < div class ="drake ">
4275+ < p > Drake's library code is not permitted to use Boost. To improve uptake,
4276+ we have chosen not to inflict this dependency on our users. It would be
4277+ permissible for unit tests to use Boost, though so far we have not seen
4278+ any need for that.</ p >
4279+ </ div >
42524280
4253-
4281+ < div class =" nondrake " >
42544282< div >
42554283< p > In order to maintain a high level of readability for
42564284all contributors who might read and maintain code, we
@@ -4325,6 +4353,7 @@ <h3 id="Boost">Boost</h3>
43254353features to the list, so this list may be expanded in
43264354the future.</ p >
43274355</ div >
4356+ </ div >
43284357
43294358< h3 id ="std_hash "> std::hash</ h3 >
43304359
0 commit comments