Proposal to extend PEP 257 (New Documentation String Spec)

[rantingrick]

On Jul 15, 6:16 pm, Chris Angelico <ros... at gmail.com> wrote:
> On Sat, Jul 16, 2011 at 4:56 AM, rantingrick <rantingr... at gmail.com> wrote:
> > Hmm, that's strange considering that code MUST be formatted in certain
> > ways or you get a syntax error (indention, colons, parenthesis, etc,
> > etc). I don't hear the masses claiming that they are going over to
> > Ruby simply because of indention.
>
> 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'

This method will preserve indention. However some might
blubber..."Yeah but then you have to remove the arrows, boo :( "...
well just watch and learn kiddo:

    >>> s = """
    def foo():
    --->for x in range(10):
    --->--->print 'foo'
    """
    >>> s = s.replace('--->', '    ')
    >>> print s

    def foo():
        for x in range(10):
            print 'foo'

    >>>

> I frequently avoid Python specifically because of its
> indentation issues. Does that mean I never use Python? No. Does it
> mean I don't post here? Obviously not.

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?

> Does it mean that further
> restrictions can automatically be grandfathered in because "there are
> already restrictions like this"? No.

Apples and oranges. Doc-string formatting is JUST as important as any
syntax formatting in the language. As long as doc-strings are optional
why the hell are you complaining?

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?

You make the argument that "lazy people" are not going to like a doc-
string spec and will refuse to create doc-strings because of it.
NEWSFLASH! "Lazy people" never take the time to create doc-strings in
the first place. Who cares about theses folks. They have the power to
choose. If you refuse to create doc-strings fine, however if you do,
the interpreter expects a certain format to be used. Everyone benefits
form properly formatted doc-strings.

> > In my mind doc-strings should ALWAYS be optional HOWEVER if the
> > programmer decides to create a doc-string THEN he must observe some
> > syntax rules or his code will throw an SyntaxError. Remember, freedom
> > is good, unbridled freedom is the root of all evil.
>
> 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.

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

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

> In other words, docstrings will define the module's interface, and
> there'll be a whole lot of utterly undocumented functions because they
> didn't merit this massive structured docstring, and it became way way
> too much work to factor things out. Either that, or people will just
> start ignoring the 80 character limit, but I'm sure you could make
> that mandatory - and that one would actually improve some things,
> because any program that wants to read Python code needs only allocate
> an 81-character buffer.

Nothing at all wrong with forcing 80 chars also. However let's stick
to one thing at a time Chris. We don't need to start up the straw-men
arguments already.

> > So what's so terrible about structure Chris? Nobody's freedom are
> > being taken away. You don't HAVE to create doc-strings, just like you
> > don't HAVE to code with Python (you do free form formatting Ruby).
> > Python is a language that is meant to be clean. Forced indention makes
> > that possible. Forced doc-string syntax will complete the circle.
>
> Python was also meant to be a programming language. Programming
> languages offer freedom to their users. Without that freedom, it's not
> a programming language but a script for another program...

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

> This is not a true programming language:http://www.kongregate.com/games/Coolio_Niato/light-bot

Okay, thanks for the info... *giggles*.

> It's a reasonably fun game, but specifically _because_ it's so
> restrictive. That is NOT what I want from a programming language or
> even a scripting language.

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

NOT