Python is readable

[Nathan Rice]

>> 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?  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.

To steal a line from Einstein, "Make things as simple as possible, but
not simpler"

>> I agree, docstrings/code comments are a pretty obvious indication that
>> code (as it exists currently) fails as a human communication medium.
>
>
> The fact that scientific journal articles start with a documentation string
> called an abstract does not indicate that scientific English fails as a
> human communication medium. Function docstrings say what the function does
> and how to use it without reading the code. They can be pulled out and
> displayed elsewhere. They also guide the reading of the code. Abstracts
> serve the same functions.

A paper, with topic introduction, methods exposition, data/results
description and discussion is a poor analog to a function.  I would
compare the abstract of a scientific paper to the overview section of
a program's documentation.  The great majority of the docstrings I see
are basically signature rehashes with added type information and
assertions, followed by a single sentence English gloss-over.  If the
code were sufficiently intuitive and expressive, that would be
redundant.  Of course, there will always be morbidly obese functions
and coders that like to wax philosophical or give history lessons in
comments.

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 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.  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.