On 12/1/23 17:42, Andrey Semashev wrote:
On 12/1/23 13:10, Julien Blanc wrote:
Le 2023-11-30 19:20, Andrey Semashev via Boost a écrit :
The example with std::function is not really the best practice, as the section follows on after that example. You should generally avoid it, as it may throw on construction/assignment and therefore break your exception safety.
Indeed. I fear, however, that people will just come up with this code, use it without understanding the implications. I think Andrzej made a very good point (https://lists.boost.org/Archives/boost//2022/05/253109.php) by saying that examples should be exempts from anti-patterns / bad code. I try to keep that in mind now when doing a review.
I can't say I fully agree with Andrzej in that post. While it may look awkward at times that library documentation contains code samples that one shouldn't (or maybe even doesn't, in their right mind) write in actual real projects, sometimes this is just the most efficient way to demonstrate a library feature (such as that a function throws an exception) or warn about certain caveats or illustrate library misuse. Library documentation writers do rely on readers having a certain level of knowledge and intelligence, so that they are able to understand which examples are merely an illustration and not intended to be copy-pasted into real code.
That said, maybe I could better articulate in text surrounding that example that such usage is the recommended way.
...is *not* the recommended way.