blob: afbb18b0096d734b4d78043e2cc643e7e5e81760 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
|
===================================================
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``.
|
