Guido sees the light: PEP 8 updated

[Marko Rauhamaa]

Chris Angelico <rosuav at gmail.com>:

> On Sun, Apr 17, 2016 at 9:01 PM, Marko Rauhamaa <marko at pacujo.net> wrote:
>> In fact, if you find yourself introducing coding "paragraphs" with
>> comments:
>>
>>     def f(...):
>>         # I'll start by doing this
>>         ...
>>         # segueing into the middle portion
>>         ...
>>         # and finish it off as follows
>>         ...
>>
>> you had better break those paragraphs off into separate functions. Just
>> turn your comments into function names.
>
> It's really easy to do this in toy examples, isn't it? But the real
> world is not so wonderful, as Alice's nanny said.

I do this in the real world, professionally. Been doing it for decades,
and it hasn't failed me so far. Exceptions exist, but they are that:
rare exceptions.

> What more often happens is that, once the function exceeds the
> stipulated maximum, it gets split somewhat arbitrarily into a "master"
> function and several "part" functions, with each part having exactly
> one call site in the driver and exactly none elsewhere. Even if the
> partial functions have reasonable names (which they don't always),
> they're still tightly bound to the master, and end up still
> functioning as a single unit.

And? That's a feature, not a bug. It makes you analyze your approach a
bit more. It makes you give names to things. It makes it more likely
that your solution really works.

And the main thing: whoever needs to come and maintain your code will
have an easier time understanding what your code is trying to
accomplish.

> Unless you can genuinely make that subfunction useful in some other
> context, there's not a lot of use splitting it into a function. You
> don't generally see those perfect "paragraphs" in real-world code.

No, that's Software Engineering 101: you split your solution into
subroutines regardless of whether those subroutines are needed in
multiple places.

(The main practical problem with the divide-and-conquer approach is the
fact that you need to drag the context around. Sometimes you have to
keep piling on function arguments, which spoil the visual advantages you
are trying to gain by partitioning your solution. One obvious solution
to the argument clutter is to carry the context in *the* object or *a*
special-purpose context object.)

The compactness requirement for the code discourages empty lines and
commenting. If find that, too, a feature rather than a bug. The code
should in general speak for itself. Well-chosen names and a compact,
elegant structure communicate the intent of the code better than
plain-English comments that will not stay current with the code anyway.


Marko