Documenting exception safety
Stephen Toledo-Brown
is key to exception safety. Unfortunately, I haven't seen much of such
documentation around for real code. I don't think it's realistic to
expect developers in general to generate (or even read, most of the
time) documentation of the level of detail in Dave Abraham's
documentation of the Standard Library.
So what do people really do?
It seems easy to add a tag into Doxygen so that an appropriate
@exception-safety comment in the code would be picked up - has anyone
had success with this approach?
Also, given that the exception safety of a function depends on the
functions it calls directly and indirectly, how do people cope with
ensuring that the documentation is up to date?
Finally, I note that Herb Sutter is now using the more general term
"error safety" - what's the chances of this catching on, given that so
much prior writing has used the term "exception safety"?
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]
David Abrahams
> On this newsgroup, Dave Abrahams has repeatedly stated that documenting
> is key to exception safety. Unfortunately, I haven't seen much of such
> documentation around for real code. I don't think it's realistic to
> expect developers in general to generate (or even read, most of the
> time) documentation of the level of detail in Dave Abraham's
> documentation of the Standard Library.
Seriously? The standard library is remarkably terse when it comes to
exception-safety documentation -- some would even say too terse. It
doesn't even spell out the basic guarantee, doing it instead by
implication. I don't think phrases like "if an exception is thrown
there are no effects" and "throws: nothing" are particularly detailed.
In fact there have been several attempts to add detail to that sort of
guarantee by people who felt it wasn't detailed enough (it does gloss
over some possible side-effects).
If you want a shorthand, that's what the terms "basic, strong, and
nothrow" are for. What could be simpler?
> Also, given that the exception safety of a function depends on the
> functions it calls directly and indirectly,
No, only directly, provided that those functions have well-documented
exception-safety contracts.
> how do people cope with
> ensuring that the documentation is up to date?
It's the same problem as making sure that any function you're calling
doesn't suddenly change its semantics, thereby altering the semantics of
the function you're writing. You have to make sure that everything is
documented, and programmers have to look at the documentation for a
function before making changes, to ensure they preserve its behavior...
that's true with respect to exception handling or any other aspect of a
function's behavior.
Too many people think it's possible to write correct software without
rigorous and complete documentation. You could even say it's impossible
by definition, because without documentation there's no way to know what
"correct" means.
> Finally, I note that Herb Sutter is now using the more general term
> "error safety" - what's the chances of this catching on, given that so
> much prior writing has used the term "exception safety"?
I think there's little chance, though I am sympathetic to the effort.
I've been saying as early as 1988 that exception-saftey was a misnomer.
--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com
ka...@gabi-soft.fr
> On this newsgroup, Dave Abrahams has repeatedly stated that
> documenting is key to exception safety. Unfortunately, I
> haven't seen much of such documentation around for real
> code. I don't think it's realistic to expect developers in
> general to generate (or even read, most of the time)
> documentation of the level of detail in Dave Abraham's
> documentation of the Standard Library.
> So what do people really do?
It depends. A lot write code which doesn't work. The others
document as Dave Abrahams suggests, and read the documentation.
Personally, I don't think it realistic to allow developers to
not write the necessary documentation. The documentation is
essential if all but the simplest code is going to work.
> It seems easy to add a tag into Doxygen so that an appropriate
> @exception-safety comment in the code would be picked up - has
> anyone had success with this approach?
> Also, given that the exception safety of a function depends on
> the functions it calls directly and indirectly, how do people
> cope with ensuring that the documentation is up to date?
The exception safety guarantees are part of a function's
contract. You don't change them once people are using the
function.
> Finally, I note that Herb Sutter is now using the more general
> term "error safety" - what's the chances of this catching on,
> given that so much prior writing has used the term "exception
> safety"?
No idea. The concept of error safety obviously predates
exception safety, and is more general, even if I'd never heard
the term before. It has always been standard practice in code
reviews to verify that the code behaves correctly in case of
errors, regardless of where the errors come from and how they
are propagated.
Most of the uses that I've seen of the expression exception
safety have been to stress that the function behaves correctly
in the presence of the "invisible" control flow paths which
result from an exception. This has been stressed simply (or
mainly) because it is something new -- before exceptions, the
control flows were explicit, and the stress was more on
verifying that error conditions were checked (including in
functions which didn't care about them) and propagated.
--
James Kanze GABI Software http://www.gabi-soft.fr
Conseils en informatique orientée objet/
Beratung in objektorientierter Datenverarbeitung
9 place Sémard, 78210 St.-Cyr-l'École, France, +33 (0)1 30 23 00 34
Roland Pibinger
wrote:
>On this newsgroup, Dave Abrahams has repeatedly stated that documenting
>is key to exception safety.
Wasn't this Herb Sutter? IIRC, David Abrahams' position is to let
exceptions 'bubble up' and catch them on the highest possible level
without looking at the type of the exception. Writing exception safe
code is the key to exception safety.
>Unfortunately, I haven't seen much of such
>documentation around for real code.
BTW, if someone recommends thorough documentation it means that he has
lost the game. He cannot enforce or direct things in code so he must
resort to documentation. (Of course, it is always a good thing to
thoroughly document important effects!)
>I don't think it's realistic to
>expect developers in general to generate (or even read, most of the
>time) documentation of the level of detail in Dave Abraham's
>documentation of the Standard Library.
>
>So what do people really do?
If you want to specify exceptions why not use C++ exception
specifications? I know, there are some annoyances WRT exception
specifications that have to be kept in mind. But they are probably
worth the trouble for any component that is assumed to specify its
interface in code as complete as possible (i.e. any component that is
used by a third party).
Best wishes,
Roland Pibinger
ka...@gabi-soft.fr
[...]
> Too many people think it's possible to write correct software
> without rigorous and complete documentation. You could even
> say it's impossible by definition, because without
> documentation there's no way to know what "correct" means.
I couldn't agree more.
In practice, I never start writing the body of a function
without at least specifying its contract. And while it is
possible to do this in your head, I find that actually writing
it out helps clarify my thinking. It's far to easy to gloss
over some important point if it is just in your head.
> > Finally, I note that Herb Sutter is now using the more
> > general term "error safety" - what's the chances of this
> > catching on, given that so much prior writing has used the
> > term "exception safety"?
> I think there's little chance, though I am sympathetic to the
> effort. I've been saying as early as 1988 that
> exception-saftey was a misnomer.
Exception safety is to exceptions what thread safety is to
threads. Perhaps another term would be more appropriate, in
both cases, but I don't see it happening. And it is the
"safety" I would object to, more than the "exception" or the
"thread".
--
James Kanze GABI Software http://www.gabi-soft.fr
Conseils en informatique orientée objet/
Beratung in objektorientierter Datenverarbeitung
9 place Sémard, 78210 St.-Cyr-l'École, France, +33 (0)1 30 23 00 34
David Abrahams
> On 3 Jan 2005 18:21:07 -0500, Stephen Toledo-Brown <bro...@uk.ibm.com>
> wrote:
>
>>On this newsgroup, Dave Abrahams has repeatedly stated that documenting
>>is key to exception safety.
>
> Wasn't this Herb Sutter?
If Herb said that, he was repeating what I've said.
> IIRC, David Abrahams' position is to let
> exceptions 'bubble up' and catch them on the highest possible level
> without looking at the type of the exception.
That's not my position; it's a practice that I use.
> Writing exception safe
> code is the key to exception safety.
>
>>Unfortunately, I haven't seen much of such
>>documentation around for real code.
>
> BTW, if someone recommends thorough documentation it means that he has
> lost the game. He cannot enforce or direct things in code so he must
> resort to documentation. (Of course, it is always a good thing to
> thoroughly document important effects!)
In that case, we've all lost "the game." Most of the effects we all care
about from a function can't possibly be enforced in code...unless you
mean in tests, of course.
>>I don't think it's realistic to
>>expect developers in general to generate (or even read, most of the
>>time) documentation of the level of detail in Dave Abraham's
>>documentation of the Standard Library.
>>
>>So what do people really do?
>
> If you want to specify exceptions why not use C++ exception
> specifications?
Maybe because they usually don't "enforce or direct" the things that are
most important to know when writing exception-safe code: they don't tell
us what has happened to the state of the system if an exception is thrown.
--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
Pete Becker
> On 3 Jan 2005 18:21:07 -0500, Stephen Toledo-Brown <bro...@uk.ibm.com>
> wrote:
>
>
>>On this newsgroup, Dave Abrahams has repeatedly stated that documenting
>>is key to exception safety.
>
>
> Wasn't this Herb Sutter?
Maybe. Could have been me, or James Kanze, or any of a number of other
people, too. Experienced programmers know that documentation is the key
to the correct use of any code. It doesn't take deep thought to see that
this implies that documentation is the key to the correct use of exceptions.
--
Pete Becker
Dinkumware, Ltd. (http://www.dinkumware.com)
Stephen Toledo-Brown
> If you want to specify exceptions why not use C++ exception
> specifications?
They don't allow me to specify, for example, whether a function meets
the Strong or Basic exception-safety criteria.
ka...@gabi-soft.fr
> Roland Pibinger wrote:
> > On 3 Jan 2005 18:21:07 -0500, Stephen Toledo-Brown
> > <bro...@uk.ibm.com> wrote:
> >>On this newsgroup, Dave Abrahams has repeatedly stated that
> >>documenting is key to exception safety.
> > Wasn't this Herb Sutter?
> Maybe. Could have been me, or James Kanze, or any of a number
> of other people, too. Experienced programmers know that
> documentation is the key to the correct use of any code. It
> doesn't take deep thought to see that this implies that
> documentation is the key to the correct use of exceptions.
To give credit where credit is due: the idea that the complete
contract of a function must be documented certainly pre-dates
anything Dave has said on the subject -- he's not that old. But
as far as I know, he is the first to insist that exception
safety didn't mean just the strong guarantee or no throw
everywhere, but rather documenting exactly what your function
does, so the user can build on it. In some ways, it's not
really different than the principles of thread safety that I
discussed with Matt Austern many, many years ago (when he was at
SGI). And of course, it does seem obvious. But it's worth
pointing out that obvious or not, no one actually said it before
Dave, and that even a language which supports built-in
post-conditions, like Eiffel, doesn't offer any possibility for
post-conditions when an exception is raised.
(Note that the importance here isn't just that your code must be
documented, but that practically, documenting its behavior in
case of an exception is almost all that is required to claim
exception safety. Almost -- I suppose that leaving the object
in a state where at least the destructor can be called on it is
usually necessary as well.)
--
James Kanze GABI Software http://www.gabi-soft.fr
Conseils en informatique orientée objet/
Beratung in objektorientierter Datenverarbeitung
9 place Sémard, 78210 St.-Cyr-l'École, France, +33 (0)1 30 23 00 34
Stephen Toledo-Brown
> Stephen Toledo-Brown wrote:
>
>>... documentation of the level of detail in Dave Abraham's
>>documentation of the Standard Library.
>
> Seriously? The standard library is remarkably terse when it comes to
> exception-safety documentation -- some would even say too terse.
I'd agree for the documentation in the Standard. But I thought I'd seen
some much more focussed exception-safety documentation on the web
somewhere, written by you.
> If you want a shorthand, that's what the terms "basic, strong, and
> nothrow" are for. What could be simpler?
Yes, they're nice & simple. And if I could get a simple doc string like
@exceptionsafety: strong
to be added for each function in the codebase I work with, I'd be much
happier. Nothing similar currently exists in this codebase. And given
that no such tag is automatically provided in Doxygen (nor in JavaDoc),
I suspect there's generally little demand for it from developers. (I
can't understand why - to me, it seems more generally useful than some
of the provided tags.)
>>Also, given that the exception safety of a function depends on the
>>functions it calls directly and indirectly,
>
> No, only directly, provided that those functions have well-documented
> exception-safety contracts.
But that "provided" is a big if.
David Abrahams
> David Abrahams wrote:
>> Stephen Toledo-Brown wrote:
>>
>>>... documentation of the level of detail in Dave Abraham's
>>>documentation of the Standard Library.
>>
>> Seriously? The standard library is remarkably terse when it comes to
>> exception-safety documentation -- some would even say too terse.
>
> I'd agree for the documentation in the Standard. But I thought I'd seen
> some much more focussed exception-safety documentation on the web
> somewhere, written by you.
There's always a trade-off between terseness and clarity. When I write
exception-safety documentation I tend to be a bit more explicit than
what's in the standard (though not a great deal more).
>> If you want a shorthand, that's what the terms "basic, strong, and
>> nothrow" are for. What could be simpler?
>
> Yes, they're nice & simple. And if I could get a simple doc string like
> @exceptionsafety: strong
> to be added for each function in the codebase I work with, I'd be much
> happier. Nothing similar currently exists in this codebase. And given
> that no such tag is automatically provided in Doxygen (nor in JavaDoc),
> I suspect there's generally little demand for it from developers. (I
> can't understand why - to me, it seems more generally useful than some
> of the provided tags.)
Most of those tags IIUC come from Javadoc, and in Java the culture of
exception-safety is much much weaker. Maybe that has something to do
with it.
>>>Also, given that the exception safety of a function depends on the
>>>functions it calls directly and indirectly,
>>
>> No, only directly, provided that those functions have well-documented
>> exception-safety contracts.
>
> But that "provided" is a big if.
My point is that it's no different than any other kind of correctness.
A function depends for its correctness on the correctness of all the
functions it calls. If they are correct, you don't need to go and
verify the functions they call.
Let's not make a mystery where none exists.
--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com
[ See http://www.gotw.ca/resources/clcm.htm for info about ]