Python is readable

[Terry Reedy]

On 3/20/2012 3:28 PM, 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?  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.

Both abstracts and doc strings are designed to be and are read 
independently of the stuff they summarize. Perhaps you do not use 
help(obj) as often as some other people do.

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

If I understand you, some devs agree. Hence the increasing use of How-to 
docs with tutorial and example material for a module separate from the 
reference entries in its section of the Library Reference.

-- 
Terry Jan Reedy