Proposal to extend PEP 257 (New Documentation String Spec)

[Chris Angelico]

On Sun, Jul 17, 2011 at 1:32 AM, rantingrick <rantingrick at gmail.com> wrote:
> On Jul 15, 6:16 pm, Chris Angelico <ros... at gmail.com> wrote:
>> Not Ruby, but to other languages. There's this guy in my house named
>> Chris who tries his best to avoid Python if the code is going to be
>> shared over any "dodgy medium" where indentation might be damaged.
>
> Are you referring to "mediums" that delete leading white-space? First
> of all you should avoid using these "mediums" at all costs HOWEVER if
> you are forced to do so there are ways to format your code to preserve
> indentation. The most easy way to do this is by marking indentation
> with arrows.
>
> def foo():
> --->for x in range(10):
> --->--->print 'foo'

So, uhh, remind me how this is better than marking indentation with braces?

> OBVIOUSLY you have no imagination Chris! I would much rather have
> forced indention in my language (and need to process code from the web
> from time to time) than to NOT have indention and be forced to read
> sloppy and poorly formatted code ALL THE TIME. Did you ever find it
> strange that most programmers format there code with indention even
> when they are not forced to do so?

No, I don't. But if I'm sharing code snippets with people on a MUD,
then I like being able to quote some code and not have to worry about
whether the other person gets a bit of extra indentation on some of
the lines (which is more common than totally destroying indentation,
but both damage Python code).

> Do you really want to have a setup (like we currently do) where people
> are just making up the rules for doc-strings as they go? Because
> setting such a president is exactly why we have a stdlib full of
> poorly formatted doc-strings?

Yes, I do. I absolutely, wholeheartedly do.

>> 1) Every syntax element MUST add indentation.
>
> Huh? Are you suggesting that syntax errors only concern indention? I
> think you'd better give a few more moments thought to that brain fart
> Chris.

Huh?

I'm making a syllogistic argument here (or something approximating to
one). By "syntax element" I don't mean every single piece of syntax,
but all the major ones - if, while, for, etc. They all demand
indentation. Let's say you're indenting 4 spaces per indent - a not
unreasonable default. Then 80 characters gives you a hard limit of 20
indentation levels, and a soft limit of 6-8 before you lose a
significant proportion of your available width to the indent.

>> 2) Strong encouragement to stick to an 80-character line
>> Conclusion: Every big function will become two smaller functions, one
>> of which calls the other.
>
> Are you nuts! I have many multi-line functions (like 50 or more lines)
> that never go passed 80 chars in width. Sure if you want to break up
> long function bodies you can but in some cases a linear flow with good
> comments is all you need (no matter how long it might be).

..... 50 lines is your idea of big? Seriously. I have maintained
monolithic functions with far, far more lines than that - and it's
just not been worth the hassle of factoring anything out. I'd have
ended up passing most of the local variables as parameters anyway, so
it's not much of a gain.

>> 3) Every function that has a docstring MUST have it fully formatted.
>> Secondary conclusion: The only functions with docstrings are the ones
>> that are meant to be called externally.
>
> WRONG! And that attitude is a MAJOR source of the problem! EVERY
> function, EVERY class, and EVERY method should include an informative
> doc string (except in the case of blindingly "self explanatory" and
> simple functions and methods).

And that's your problem. You will have a maintenance nightmare because
every factoring-out of a function will give you twice as many
docstrings to maintain; you're forced to put something lengthy at the
top of what's basically just another part of the same function. That's
why I said that demanding properly-formatted docstrings will mean that
those factored-out functions will be treated as part of the SAME
function, and not docstringed at all - it's just not worth the hassle.
(Or, more likely, a requirement like that will lead people to just not
factor out the function at all.)

> FREEDOM IS GOOD, UNBRIDLED FREEDOM IS THE ROOT OF ALL SORROWS!

Yeah, I don't buy that one. All freedom is within boundaries;
unbridled freedom (what most people would call anarchy) has a tendency
to automatically bound itself, usually by "whoever has the biggest gun
makes the rules" in a societal context.

> <sarcasm> Oh yes Chris you are SO correct. Forcing people to write
> good doc-strings is going to be Python's down fall. How did i not see
> this? You are so wise! And your straw-men are so DAMN convincing.</
> sarcasm>

Python's downfall? Nah, not likely. There've been too many of those,
and it's still here. Ranting Rick's downfall? Also not likely. My
downfall at 2AM after a long show bumping out? That's more plausible.
Someone needs to remind me not to feed the trolls...

ChrisA