[Python-Dev] cpython: Describe the default hash correctly, and mark a couple of CPython

[Nick Coghlan]

On Sun, May 20, 2012 at 9:04 PM, Charles-François Natali
<cf.natali at gmail.com> wrote:
> Is documenting such implementation details really a good idea?
> Apart from preventing further evolutions/improvements/fixes (like the
> recent hash randomization), I don't see any benefit in exposing such
> details.
> FWIW, I clearly remember Josh Bloch warning against this type of
> documentation in one of its presentations (and in his excellent
> "Effective Java").

We've been weeding a lot of them out over time (e.g. by deleting them
rather than updating them when they change). However, keeping them can
be useful for a couple of reasons:
- sometimes we're explicitly OK with people relying on certain CPython
behaviour (or genuinely want to help them understand that behaviour)
- sometimes it's useful as an additional hint to authors of other
implementations

Mostly (as in this case) they're just due to the past blurriness of
the distinction between Python-the-language and
CPython-the-reference-implementation, though.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia