Proposal to extend PEP 257 (New Documentation String Spec)

[Chris Angelico]

On Sat, Jul 16, 2011 at 4:56 AM, rantingrick <rantingrick 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.
There are plenty of other languages that he can use... oh wait, that's
me. Yes, 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. Does it mean that further
restrictions can automatically be grandfathered in because "there are
already restrictions like this"? No.

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

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.

> 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... such things
can be useful, but are not the same.

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

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.

Chris Angelico