Re: docs patch: dicts and sets
- From: rurpy@xxxxxxxxx
- Date: 20 May 2007 16:51:04 -0700
On May 20, 3:12 am, Raymond Hettinger <pyt...@xxxxxxx> wrote:
On May 13, 4:52 pm, r...@xxxxxxxxx wrote:
Dismissing this as not a "real problem" is both wrong
and offensive to people taking the time to actually
propose improvements.
I should have elaborated on what I meant by saying that there is not a
real problem. Another way to put it is that the docs are sufficient
when they say that set ordering is arbitrary. That should be a cue to
not have *any* expectations about the internal ordering of sets and
dicts.
I disagree. When reading the docs, the reader will
always have and need assumtions because the docs can't
describe all behavior from first priciples. Every
programmer will bring and apply his or her understanding
of how computers and computer programs operate under
the hood.
For example, nowhere in the "file" object documentation
does is say the files are read starting from byte 0.
It relies on the fact that the reader will have that
expectation based on previous experience with computers.
The are two basics principles that I think most
programmers apply sans explicit contradictory
information:
* That documentation about behavior applies within
the bounds of a single execution.
* That computers are fundamentaly deterministic
(with a possible exception for code running in
Microsoft OSes. :-)
When I read that sets return items in arbitrary
order (and the docs aren't even that specific),
I make a natural assumption that, no information
provided to the contrary, within a single program
execution the order will be arbitrary. Since it
says nothing about between execution, the very
strong general rule applies: that if no obvious
source of volatilty or dependence on environment
exist, the same program should produce the same
results.
Any further documentation of behavior would be a mistake because it
would of necessity expose implementation specific details.
You don't need to make promises to explain surprising
behavior. (The word "may" is amazingly useful in these
cases :-) A "for example" that exposes implementation
details make no promises yet can make clear non-intuative
behavior. A concise but clear noting of the surprising
behavior seen by the OP would improve the clarity of the
documentation, not harm it.
For
instance, there is another intentionally undocumented observable
behavior that sets and dicts change their internal order as new
members are added. It is also intentional that Python makes almost no
promises about the location of objects in memory. IIRC, the only
guarantees made about object identity are that "a is a" is always true
and None can be tested with "is".
One last comment. While I treat opinions from Python
experts on Python technical details with great respect
and appreciation, opinions on documentation should be
viewed with much greater skepticism. It can be difficult
for an expert to view Python with the same eyes as a
non-guru level programmer, yet the latter is (or
should be) the target audience of the documentation.
[And please, let's not start the reference vs tutorial
thing!]
.
- References:
- docs patch: dicts and sets
- From: Alan Isaac
- Re: docs patch: dicts and sets
- From: Raymond Hettinger
- Re: docs patch: dicts and sets
- From: rurpy
- Re: docs patch: dicts and sets
- From: Raymond Hettinger
- docs patch: dicts and sets
- Prev by Date: Re: python shell
- Next by Date: Re: Getting the member of a singleton set
- Previous by thread: Re: docs patch: dicts and sets
- Next by thread: docs patch: dicts and sets
- Index(es):
Relevant Pages
|
