Re: [scope] A few questions

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2023-12-01 14:58:10

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.