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 beenvector::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
.