[Python-ideas] Python docs: page: In what ways in None special
rhodri at kynesim.co.uk
Tue Aug 14 13:45:59 EDT 2018
(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
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.
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 
 Misquoting Michael Flanders from the introduction to "The
Hippopotamus Song" on "At The Drop Of A Hat".
Rhodri James *-* Kynesim Ltd
More information about the Python-ideas