Python is readable

[Steven D'Aprano]

On Tue, 20 Mar 2012 15:28:25 -0400, Nathan Rice wrote:

>>> This is one of my gripes with the dogmatic application of the "break
>>> it into multiple statements" mantra of Python.
>>
>> I must admit I don't recognise that one, unless you're talking about
>> "not everything needs to be a one liner".
>> ...
>> Perhaps you could give some examples (actual or contrived) of stuff
>> where "breaking it into multiple statements" is a bad thing?
> 
> One example is performing a series of transformations on a collection of
> data, with the intent of finding an element of that collection that
> satisfies a particular criterion.  If you separate out the individual
> transformations, you need to understand generators or you will waste
> space and perform many unnecessary calculations.  If you only ever do a
> single transformation with a clear conceptual meaning, you could create
> a "master transformation function," but what if you have a large number
> of potential permutations of that function?  

I'm sorry, that is far too abstract for me. Do you have a *concrete* 
example, even an trivial one?



> What if you are composing
> three or four functions, each of which is conditional on the data?  If
> you extract things from a statement and assign them somewhat arbitrary
> names, you've just traded horizontal bloat for vertical bloat (with a
> net increase in volume), while forcing a reader to scan back and forth
> to different statements to understand what is happening.

First off, vertical bloat is easier to cope with than horizontal bloat, 
at least for people used to reading left-to-right rather than vertically. 
There are few anti-patterns worse that horizontal scrolling, especially 
for text.

Secondly, the human brain can only deal with a limited number of tokens 
at any one time. It's easier to remember large numbers when they are 
broken up into chunks:

824-791-259-401 versus 824791259401

(three tokens, versus twelve)

Likewise for reading code. Chunking code into multiple lines instead of 
one long expression, and temporary variables, make things easier to 
understand, not harder.

http://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two

And thirdly, you're not "forcing" the reader to scan back and forth -- or 
at least if you are, then you've chosen your functions badly. Functions 
should have descriptive names and should perform a meaningful task, not 
just an arbitrary collection of code.

When you read:

x = range(3, len(sequence), 5)

you're not forced to scan back and forth between that line and the code 
for range and len to understand it, because range and len are good 
abstractions that make sensible functions.

There is a lot of badly written code in existence. Don't blame poor 
execution of design principles on the design principle itself.


[...]
> Also, because of Sphinx, it is very common in the Python community weave
> documents and code together in a way that is convenient for authors but
> irritating for readers.

I don't know about "very common". I suspect, given the general paucity of 
documentation in the average software package, it is more like "very 
rare, but memorable when it does happen".


> I personally would prefer not to have to scroll
> past 100 lines of a tutorial with examples, tests and what not in order
> to go from one function to another.

Agreed. Docstrings should use a minimal number of examples and tests. 
Tutorials and extensive tests should be extracted into external documents.


> It would be really awesome if
> everyone used links to that material in docstrings, and the default
> sphinx theme created an inline collapsible iframe that included that
> material for the HTML version.  Don't get me wrong, I adore Sphinx, the
> problem here is people who are lazy or don't know the right way to
> structure docs.

+1000


-- 
Steven