[Boost-users] ScopeExit Review

From: Pavel Vozenilek (pavel_vozenilek_at_[hidden])
Date: 2007-08-22 18:07:06

This is short review of the documentation. I plan to look into it more on 
VC9,
newer versions of GCC and with the AMD profiler.

In my opinion the library should be included in Boost (it has the features
I asked for and doesn't have the problems I disliked) but the documentation
should be more "tired-programmer-with-no-time" friendly.

IMO the first page should contain something like this:

RAII can be implemented:
1. By creating a special purpose class. Example.
2. By using ScopeGuard (there's already one in Boost hiding deeply in the 
MultiIndex
    library - this should be mentioned). 2 examples - one simple, one
    hideously complicated to show the limitations.
3. By using ScopeExit. 2 examples - one the most simple, the second complex.
    It should be said that the values are passed by value (and when) and 
mentioned
    how to pass them by reference.

An example how one can redefine the long macros BOOST_SCOPE_EXIT
and BOOST_SCOPE_EXIT_END with something shorter should be provided.

Then there should be table listing known C++ compilers and limitations  of 
ScopeExit here:
* has it native typeof or emulation?
* works with multiple TU?
* works in templates?
* more efficient version can be used (if it is stays separated, it should be 
automatic IMHO)
* rough estimate of compile time dependency on number of ScopeExits in a TU
   (this is really important, that's what killed the SMART_ASSERT library).
   Possibly also effect on linking time (how much of extern stuff does it 
put into object files).
* whether C99 features can be used
  (possibly every example could have C++98 and C99 variant)

Ideally there would be link to example for every compiler in the table
showing what fails and what works.

This first page should be sufficient enough for 90% of users.

Other pages:
Every other macro mentioned in the documentation should start with
information who may be interested in it and for who it is irrelevant.
This information should be visually separated from the rest of the text.

If possible the "experimental" macros should be removed
from the documentation - this word just sends a cold chill down my neck
and could easily discourage people from using the library.

Whether the concept is useful:
In my opinion yes because:
a) Such a feature was added into the D language
    and I know one proprietary scripting language which implemented
    it as well and it had helped to find a few hard to notice bugs.

b) The ability to put cleanup code near to related code is invaluable.
    Cleanup code gets rarely tested (or may be practically untestable) and 
every
    bit which helps to spot a bug is invaluable.

c) The library helps to reduce number of nested blocks, one of the most
    error prone construct.

d) The library could be also very useful for those who maintain
    or gradually rewrite a large legacy codebase since it allows
    minimal and local changes.

Whether it is good to add yet another macro-library to Boost:
* Well, that's the way it works. Perhaps C++1x will get native
  on_exit { } construct.

The current library allows to put a breakpoint into the code which
makes more debugeable code than, say, one using std algorithms.

The information whether local variables from the macro list
will show up in the debugger may be put somewhere in the docs.

-------------------

I'll take deeper look on the code later. I wrote this short review to catch 
up
the end of review period.

--------------------

The documentation may also mention alternative ScopeGuard implementation
in http://tnfox.sourceforge.net/TnFOX-0.87/html/df/d4f/group__rollbacks.html
can be mentioned in passing. It features so called "group undo"
for multiple ScopeGuards, providing something like transactions.

/Pavel