[Python-ideas] Python docs: page: In what ways in None special

Rhodri James 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 
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


More information about the Python-ideas mailing list