Cpp Coding Standards/ERR/Safe
From Apache OpenOffice Wiki
Contents
Function Safety Guarantees
Id: ERR:Safe
Summary
Provide the strongest error-safety guarantee for each function that does not punish callers who do not need it. The basic guarantee is always necessary.
Explanation
The three guarantees are:
- Basic Guarantee
- Errors leave the program at least in a valid state. Classes's invariants are kept, there are no memory leaks, etc. Further details of this state may however not be predictable.
- Strong Guarantee
- This is like a transaction. After the function call, the program either has the intended state (as it should be after the function call) or the same state as before the function was called.
- No-fail Guarantee
- The function can not fail.
The rule is: Every function has to provide at least the basic guarantee.
How to document the guarantees
For a free function or a non-const member function, the basic guarantee is the default. If it provides a stronger guarantee, mention this in the documentation. (Use the documentation tag "@onerror".)
For a const-member function, the no-fail guarantee is the default. It has to be documented, if its guarantee is weaker, but it also has to be at least the basic guarantee.
See also
ERR:NoFail - which functions never fail
References
For the three kinds of guarantee:
- D. Abrahams: "Exception Safety in STLPort" (STLPort website, 1996)
- Bjaarne Stroustrup: "The C++ Programming Language (Special 3rd Edition)" (Addison Wesley, 2000)