has_key doc could be clearer

[terryjreedy]

BPO	4243
Nosy	@loewis, @birkenfeld, @terryjreedy, @giampaolo, @benjaminp

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2008-10-31.20:42:07.623>
created_at = <Date 2008-10-30.17:48:24.265>
labels = ['docs']
title = 'has_key doc could be clearer'
updated_at = <Date 2008-11-01.19:42:02.032>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2008-11-01.19:42:02.032>
actor = 'loewis'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2008-10-31.20:42:07.623>
closer = 'benjamin.peterson'
components = ['Documentation']
creation = <Date 2008-10-30.17:48:24.265>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 4243
keywords = []
message_count = 14.0
messages = ['75374', '75376', '75378', '75381', '75416', '75417', '75424', '75427', '75433', '75443', '75444', '75445', '75446', '75449']
nosy_count = 7.0
nosy_names = ['loewis', 'georg.brandl', 'terry.reedy', 'giampaolo.rodola', 'benjamin.peterson', 'LambertDW', 'darcy@druid.net']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue4243'
versions = ['Python 2.6', 'Python 2.7']

[terryjreedy]

2.6 lib ref builtin types, mappings, has_key doc now says
"dict.has_key(key) is equivalent to key in d, but deprecated."
Posters on c.l.p found this confusing. Which is deprecated?
I agree that this could be confusing to a beginner.

D'Arcy J.M. Cain suggests
"dict.has_key(key) is deprecated. Use "key in dict" instead."
Or "Use the replacement ..."
Or "Use the new version ..."

[loewis]

Out of curiosity: is that really ambiguous in plain English?

[giampaolo]

English is not my first language but it seems obvious to me that the
suggestion is using:

>> key in dict

...instead of:

>> dict.has_key(key)

The only thing which may be confusing is the dictionary which is first
called "dict" and then "d", in which case the following modification
should be made:

• dict.has_key(key) is equivalent to key in d, but deprecated.
  + dict.has_key(key) is equivalent to key in dict, but deprecated.

[birkenfeld]

If I understand English correctly, I don't see an ambiguity.

Probably the poster(s) on c.l.p didn't look properly and read something
like "equivalent to key in d, but the latter is deprecated".

The d/dict inconsistency should be fixed.

[lambertdw]

The D'Arcy J.M. Cain wording is clearer.

"dict.has_key(key) is deprecated. Use "key in dict" instead." would
improve python.

[darcydruidnet]

The original is not technically ambiguous modulo the dict/d issue. The
suggested text just makes it more obvious.

We just don't want to reduce the possibility of no confusion. :-)

[terryjreedy]

I believe "deprecated" at the end is the sort of dangling modifier
deprecated by English style books I have read. I felt it to be
sufficiently awkward and potentially confusing, at least for a moment,
to be worth a few minutes to report and change. Another suggestion for
improvement:

"dict.has_key(key), now deprecated, is equivalent to key in dict, the
recommended replacement."

With or without the (optional) final phrase, this is smoother and
impossible to misread.

[benjaminp]

After consulting with an English teacher who agreed that the phrasing
was awkward, I fix it up in r67070.

[loewis]

Benjamin: Thanks for asking your teacher! It's curious that all the
foreigners have no problems with the formulation, and all the native
speakers do... There is clearly something to the English language that
we haven't mastered yet.

[terryjreedy]

Benjamin: I thank you too for verifying that I was not crazy.

Martin: I noticed native/non-native split too, and chalked it up to a
subtle difference between German and English.

For future reference, the problem with the original, as I see it now, is
a subtle interaction between syntax and semantics. The original
sentence combined two thoughts about has_key. The two should be either
coordinate (parallel in form) or one should be clearly subordinate. A
subordinate modifier should generally be closer to the subject,
especially if it is much shorter. Making that so was one of my
suggestions. The coordinate form would be 'but it is deprecated'. But
this does not work because 'it' would be somewhat ambiguous because of
the particular first modifier.

The following pair of sentences illustrate what I am trying to say.
Guido was once a Nederlander, but he moved to America.
Guido was once a student of Professor X, but he moved to America.
In English, the second 'he' is ambiguous because of the particular first
modifier.

So, to me, 'but deprecated' at the end of the sentence reads as either a
misplaced subordinate form or as an abbreviated coordinate form that is
at least somewhat ambiguous because of the meaning of the other modifier.

[loewis]

The following pair of sentences illustrate what I am trying to say.
Guido was once a Nederlander, but he moved to America.
Guido was once a student of Professor X, but he moved to America.
In English, the second 'he' is ambiguous because of the particular first
modifier.

Ah - thanks for the explanation. I now recall that native speakers
typically associate "it" (or "he") with the *last* thing/person being
mentioned. If this is the case, it's indeed different from German;
the literal translation of the second sentence would not usually be
considered ambiguous:

Guido war früher Student von Professor X,
(er) ist aber nach Amerika umgezogen.

If we wanted to express that it is X who moved, we would say

Guido war früher Student von Professor X,
der/welcher aber nach Amerika umgezogen ist.

which translates to

Guido was once a student of Professor X, who moved
to America, though. (couldn't figure out how to put the
"but" into that sentence)

So in German, it seems, backward references go typically to
the subject of the main phrase.

[birkenfeld]

Forgive me for playing stupid here, but I want to understand English
better. I would fully understand the confusion had the sentence been

"dict.has_key(key) is equivalent to key in d, but it is deprecated."

Terry's and Martin' example sentences are transferable to that. However,
the actual sentence was

"dict.has_key(key) is equivalent to key in d, but deprecated."

Let me try to construct a similar sentence:

"Guido was once a colleague of Joe, but much smarter."

Can the "but" clause really be taken as referring to Joe? Or is it
simply not an English sentence? ;)

[darcydruidnet]

I think a clarification is in order. The sentence being changed was
perfectly and mathematically correct. If you laid it out on a
blackboard and parsed it (remember those days?) you could prove that it
said the correct thing. No one is disputing that I think. The change
is simply to make it easier on the guy who is reading the manual in a
rush, under a deadline and who might misread it. His fault but there is
no harm in protecting him a little.

[loewis]

> Terry's and Martin' example sentences are transferable to that.
> However, the actual sentence was
> "dict.has_key(key) is equivalent to key in d, but deprecated."

The sentence being changed was perfectly and mathematically correct.

I'm not so sure about that anymore. Reading the post in

http://www.englishforums.com/English/RepetitionSubjectPronoun/cqjlw/post.htm

it now seems to me that the part after the comma is a separate sentence,
and both the subject pronoun and the verb are omitted (as an ellipsis).
So the full sentence would indeed read

"dict.has_key(key) is equivalent to key in d, but it is deprecated."

which then would be ambiguous as discussed.