mirror of
https://github.com/llvm/llvm-project.git
synced 2025-04-18 11:46:40 +00:00
2684a0966d
We've been applying ``[[nodiscard]]`` more liberally recently, but we don't have any documented guidance on when it's correct to add it. This patch adds that guidance. Follow-up patches will gradually apply it to the code base.
43 lines
1.8 KiB
ReStructuredText
43 lines
1.8 KiB
ReStructuredText
===================================================
|
|
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``.
|