diff options
author | Nikolas Klauser <nikolasklauser@berlin.de> | 2024-03-29 19:33:46 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-03-29 19:33:46 +0100 |
commit | 2684a0966d5c84071c811c68ec25e41a0beb26f4 (patch) | |
tree | a343249cc3e700ac1b8c89c53cee4d02f8b11240 | |
parent | beaff78528747dfbd50f9f4df77ac25f459075be (diff) | |
download | llvm-2684a0966d5c84071c811c68ec25e41a0beb26f4.zip llvm-2684a0966d5c84071c811c68ec25e41a0beb26f4.tar.gz llvm-2684a0966d5c84071c811c68ec25e41a0beb26f4.tar.bz2 |
[libc++] Document guidelines for applying [[nodiscard]] (#84000)
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.
-rw-r--r-- | libcxx/docs/DesignDocs/NodiscardPolicy.rst | 42 | ||||
-rw-r--r-- | libcxx/docs/index.rst | 1 |
2 files changed, 43 insertions, 0 deletions
diff --git a/libcxx/docs/DesignDocs/NodiscardPolicy.rst b/libcxx/docs/DesignDocs/NodiscardPolicy.rst new file mode 100644 index 0000000..afbb18b --- /dev/null +++ b/libcxx/docs/DesignDocs/NodiscardPolicy.rst @@ -0,0 +1,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``. diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst index aa1bd4b..2a7e47d 100644 --- a/libcxx/docs/index.rst +++ b/libcxx/docs/index.rst @@ -189,6 +189,7 @@ Design Documents DesignDocs/FeatureTestMacros DesignDocs/FileTimeType DesignDocs/HeaderRemovalPolicy + DesignDocs/NodiscardPolicy DesignDocs/NoexceptPolicy DesignDocs/PSTLIntegration DesignDocs/ThreadingSupportAPI |