Wording in TotW 153 "Don't use using-directives" may mislead readers

[tonyelewis]

Thanks to all involved in the work on all the Abseil TotW material - it's a fantastic resource.

I have some feedback on TotW #153 "Don't use using-directives". I realise this is unsolicited so please accept my apologies if it is unwelcome and/or wrong.

I think the paragraph:

The vast majority of C++ users think that the using-directive is injecting names into the scope where it’s declared. In the example above, that would be the scope of the function. In reality, the names are injected into the nearest common ancestor of the target namespace (::testing) and the usage namespace (::totw::example::anonymous). In our example, that’s the global namespace!

…is worded in a way that risks misleading readers. Or to put it more honestly: I got myself a bit confused by its wording ;).

AFAIU (from http://eel.is/c++draft/basic.namespace#namespace.udir-2 ), there are two relevant scopes here:

1. the scope within which the names are available for use in unqualified lookup
2. the scope in which any such unqualified lookup will treat them as if they reside

I think the above paragraph is correctly highlighting that the lookup-as-if scope is the nearest common ancestor scope:

1. availability : scope of using directive ✔️
2. lookup-as-if : nearest common ancestor scope ✔️

…but I think the paragraph's wording conflates these two notions and hence risks misleading readers into thinking that both these notions use the nearest common ancestor scope, ie that:

1. availability : nearest common ancestor scope ❌
2. lookup-as-if : nearest common ancestor scope ✔️

…and I think opening sentence will prime readers to be particularly susceptible to accepting a claim they find highly counter-intuitive. Furthermore, I think the code snippet that follows after the paragraph reinforces the misunderstanding by drawing an equivalence with a dump of using declarations in the global namespace.

In case it's helpful, here's one possible attempt at another wording:

[…] In reality, though the names it injects are indeed only accessible within that scope, any unqualified lookup of those names within that scope will treat the names as having been injected into the nearest common ancestor of the target namespace […]

(FWIW, for my tastes, I also think this tip overstates the applicability of the rule. I absolutely agree with its applicability for Google-like code-base sizes, predicted project lifetimes, dependency loads, availability of tooling/support etc. But I think violation of the rule may be completely reasonable in other contexts that involve wildly different trade-offs.)

I hope that you find this issue more helpful than annoying.