| =================================================== |
| Guidelines for applying ``[[nodiscard]]`` in libc++ |
| =================================================== |
| |
| Libc++ adds ``[[nodiscard]]`` to functions in a lot of places. The standards |
| committee has decided to not have a recommended practice where to put them, so |
| this document lists where ``[[nodiscard]]`` should be applied in libc++. |
| |
| When should ``[[nodiscard]]`` be added to functions? |
| ==================================================== |
| |
| ``[[nodiscard]]`` should be applied to functions |
| |
| - where discarding the return value is most likely a correctness issue. |
| For example a locking constructor in ``unique_lock``. |
| |
| - where discarding the return value likely points to the user wanting to do |
| something different. For example ``vector::empty()``, which probably should |
| have been ``vector::clear()``. |
| |
| This can help spotting bugs easily which otherwise may take a very long time |
| to find. |
| |
| - which return a constant. For example ``numeric_limits::min()``. |
| - which only observe a value. For example ``string::size()``. |
| |
| Code that discards values from these kinds of functions is dead code. It can |
| either be removed, or the programmer meant to do something different. |
| |
| - where discarding the value is most likely a misuse of the function. For |
| example ``find``. |
| |
| This protects programmers from assuming too much about how the internals of |
| a function work, making code more robust in the presence of future |
| optimizations. |
| |
| What should be done when adding ``[[nodiscard]]`` to a function? |
| ================================================================ |
| |
| Applications of ``[[nodiscard]]`` are code like any other code, so we aim to |
| test them. This can be done with a ``.verify.cpp`` test. Many examples are |
| available. Just look for tests with the suffix ``.nodiscard.verify.cpp``. |
