(Sorry to break threading on this. In a fit of idiocy I deleted the
original email before realising I wanted to reply.)
First off, thanks for doing this Jonathan. Documentation is usually a
thankless task, so we ought to start by thanking you!
I have a few comments on both content and style, good and bad. Starting
with style, I notice you tend to write in short sentences. This is
generally a good thing, but sometimes you make them too short. This
gets really visible when you start sentences with "And" or "But"; my old
English teacher would have menaced you with a ruler for such bad
grammar. You can start a sentence with a conjunction, but it adds extra
emphasis that you don't usually want. The start of the "Why None?"
section is a good example. It reads like:
"Sometimes a value is required. But (pay careful attention to this,
it's important and there will be a quiz later) we're not able to provide
one."
I exaggerate for effect, of course, but it would read more easily as:
"Sometimes a value is required but we're not able to provide one."
On 'None is a constant':
Erm. I think you've got carried away with simplifying this and gone
down a blind alley. None is a literal, and like any other literal can't
be rebound. Either this entire section is irrelevant or you meant to
explain that there is only one "NoneType" object.
Constant is a bit of a loaded term in Python, and I think you've fallen
foul of it here.
On 'None is the default return value':
I really dislike the term "falls off the bottom". I can't think of
anything similarly short and expressive, but I grimaced when I saw it.
The 'list gotcha' is a good example of how None is used as the default
return value and why programmers should pay attention, but it doesn't
deserve it's own subsection. It's a direct consequence of None being
the return value.
On 'None can signal failure':
Here's where I think None stops being special in the document. None can
signal failure. So False, 0, an empty string, a negative number or
pretty much anything else. If you want to have a section on how None is
used, that great, but having this in the section "How None is special"
is just wrong.
On 'None as a placeholder default':
Ditto. It's common to use None as a placeholder for a mutable type;
explaining that common gotcha here would be good.
Epigraphs:
If you're going to quote Sherman, you need to expand on the uniqueness
of None. Not doing that just makes it look irrelevant. It's not
irrelevant, it's a tigger [1]
[1] Misquoting Michael Flanders from the introduction to "The
Hippopotamus Song" on "At The Drop Of A Hat".
--
Rhodri James *-* Kynesim Ltd
_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/
