On 3/24/2018 5:49 AM, Chris Angelico wrote:
On Sat, Mar 24, 2018 at 3:41 PM, Steven D'Aprano firstname.lastname@example.org wrote:
To keep this a manageable length, I've trimmed vigourously. Apologies in advance if I've been too enthusiastic with the trimming :-) On Sat, Mar 24, 2018 at 05:09:54AM +1100, Chris Angelico wrote:
"SLNB"? Undefined acronym. What is it? I presume it has something to do with the single-statement variable.
Statement-Local Name Binding, from the title of the PEP. (But people probably don't read titles.)
Indeed. In case it isn't obvious, you should define the acronym the first time you use it in the PEP.
Once again, I assumed too much of people. Expected them to actually read the stuff they're discussing. And once again, the universe reminds me that people aren't like that. Ah well. Will fix that next round of edits.
To be fair to the readers, you don't indicate you're going to use part of the title as an acronym later. I certainly didn't get it, either, and I read the title and PEP. So I'm in the group of people you assumed too much of.
The traditional way to specify this would be to change part of the title or first usage to:
"Statement-Local Name Binding (SLNB)".
Which is a signal to the reader that you're going to use this later and they should remember it.
I don't know if it's frowned upon, but I wouldn't put this in the title. Instead, I'd put it in the body of the PEP on first usage. And I'd also make that usage in the first paragraph, instead of many paragraphs in.