Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #9494 > unrolled thread

Proposal to extend PEP 257 (New Documentation String Spec)

Back to article view | Back to comp.lang.python

Contents

  Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-14 16:02 -0700
    Re: Proposal to extend PEP 257 (New Documentation String Spec) Ben Finney <ben+python@benfinney.id.au> - 2011-07-15 10:24 +1000
    Re: Proposal to extend PEP 257 (New Documentation String Spec) Michael Hrivnak <mhrivnak@hrivnak.org> - 2011-07-15 02:00 -0400
    Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-15 17:13 +1000
      Re: Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-15 11:56 -0700
        Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-16 09:16 +1000
          Re: Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-16 08:32 -0700
            Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-17 02:25 +1000
            Re: Proposal to extend PEP 257 (New Documentation String Spec) Andrew Berg <bahamutzero8825@gmail.com> - 2011-07-16 18:03 -0500
              Re: Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-16 16:25 -0700
                Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-17 09:45 +1000
            Re: Proposal to extend PEP 257 (New Documentation String Spec) Andrew Berg <bahamutzero8825@gmail.com> - 2011-07-16 18:44 -0500
        Re: Proposal to extend PEP 257 (New Documentation String Spec) Michael Hrivnak <mhrivnak@hrivnak.org> - 2011-07-16 15:23 -0400
          Re: Proposal to extend PEP 257 (New Documentation String Spec) Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-07-17 13:10 +1000
            Re: Proposal to extend PEP 257 (New Documentation String Spec) Tim Chase <python.list@tim.thechases.com> - 2011-07-17 06:11 -0500
              Re: Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-17 10:30 -0700
        Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-17 09:09 +1000
    Re: Proposal to extend PEP 257 (New Documentation String Spec) George Rodrigues da Cunha Silva <georger.silva@gmail.com> - 2011-07-15 12:44 -0300

#9494 — Proposal to extend PEP 257 (New Documentation String Spec)

Hello Folks,

Lately i have been musing over the ideas of method tagging.
Specifically i am referring to method identifiers. As most of you know
i had proposed to add "syntactical markers" to the language to deal
with the ambiguities that arise whist eyeball parsing sub classed
methods that clobber virtual methods. HOWEVER that idea caused some
fierce controversy within the community, and i can partly understand
why.

Although i strongly believe in proper documentation (even to the point
of forcing syntax on folks) i understand that we cannot implement such
a thing without major growing pains. So with that being said, i have
formulated a new battle plan to defeat this problem of ambiguity.

Unlike most languages out there we have doc-strings; and do we realize
how great this gift is? Sometimes i wonder because you folks should
really be using them like they are going out of style!

As we all know PEP 257 lays out some ground rules for documentation
strings HOWEVER i feel this PEP did no go far enough. Too many folks
are refusing to document properly and so i will take this time to
hammer out a spec. I would like to comments for or against.

---------------------------------------
 New Syntax Specification For Documentation Strings
---------------------------------------

""" {DOC TAG HERE}: {MODULE_NAME|SHORT_SUMMARY_HERE}.
{NEWLINE}
{LONG_DESCRIPTION_HERE}
{NEWLINE}
Arguments: (if applicable)
    {ARGUMNET_1} <{TYPE}>:
        ARGUMENT_1_DESCRIPTION}
    {ARGUMNET_2} <{TYPE}>:
        ARGUMENT_2 DESCRIPTION}
    {ARGUMNET_N} <{TYPE}>:
        ARGUMENT_N_DESCRIPTION}
{NEWLINE}
"""

As you can see my spec introduces some new ideas to writing doc-
strings. Specifically the "DOC TAG" and {ARG TYPES} are new. Also i've
found it much more useful to separate args and their respective
descriptions with a newline and indention.

---------------------------------------
 Example: Module Documentation String.
---------------------------------------

"""Module <simpledialog.py>:

This module handles Tkinter dialog boxes.
It contains the following public symbols:

    Dialog <class>:
        A base class for dialogs.

    askinteger <function>:
        Get an integer from the user.

    askfloat <function>:
        Get a float from the user.

    askstring <function>:
        Get a string from the user.

"""

I don't know how i feel about marking classes and functions since IF
we follow the python style guide we don;t need to; but that's IF we
FOLLOW it people, IF.

---------------------------------------
 Example: Func/Meth Documentation String.
---------------------------------------

def askinteger(parent, title, prompt, **kw):
    """ Interface: Get an integer from the user.

    Return value is an integer.

    Arguments:
        title <string>:
            the dialog title
        prompt <string|integer|float>:
            the label text
        **kw:
            see SimpleDialog class


---------------------------------------
 Example: Class Inheritance Documentation Strings.
---------------------------------------

class Base():
    def __init__(self):
        """ Internal:"""
        self.m1()

    def m1(self, *args):
        """Overide: """
        pass

class Derived(Base):
    def __init__(self):
        Base.__init__(self)

    def _m1(self):
        """ Internal: blah"""

    def m1(self):
        """ Clobbered: see Base for detail"""

    def m3(self):
        """ Interface: Blah"""

---------------------------------------
 Tags For Documentation Strings
---------------------------------------

 Module:
    The module tag is to be used for module doc strings.

 Virtual:
    The virtual tag is for methods residing in a base class
    that are created specifically to be overridden. Of course as we
    all know every Python methods/function is virtual by default
    however the point of this is to make the code more readable!

 Override:
    This tag should be placed in a derived class's method which has
    clobbered a base method. Typically you can just defer the reader
    to look up the base class for more info.

 Internal:
    This tag should be used on all internal methods (psst: the ones
that
    start with a single underscore *ahem* or SHOULD start with a
single
    underscore!).

 Interface:
    This tag is be used for interface method/function doc strings.
This
    is probably the most important tag. If you don't do any tagging AT
    LEAST tag the interface methods and functions. However i must
    remind you that all these tags are very important.

[toc] | [next] | [standalone]

#9495

rantingrick <rantingrick@gmail.com> writes:

> ---------------------------------------
>  New Syntax Specification For Documentation Strings
> ---------------------------------------
>
> """ {DOC TAG HERE}: {MODULE_NAME|SHORT_SUMMARY_HERE}.
> {NEWLINE}
> {LONG_DESCRIPTION_HERE}
> {NEWLINE}
> Arguments: (if applicable)
>     {ARGUMNET_1} <{TYPE}>:
>         ARGUMENT_1_DESCRIPTION}
>     {ARGUMNET_2} <{TYPE}>:
>         ARGUMENT_2 DESCRIPTION}
>     {ARGUMNET_N} <{TYPE}>:
>         ARGUMENT_N_DESCRIPTION}
> {NEWLINE}
> """

I use reStructuredText formatting in my PEP 257 docstrings:

    def frobnicate(spong, mode="wibble"):
        """ Frobnicate the spong.

            :param spong: The SpongDrabble instance to be frobnicated.
            :param mode: Specific frobnication mode to use. Valid modes
                are "wibble", "wobble", "warble".
            :return: The blagule from the frobnication.

            Note that the Weebly-Ruckford algorithm is used for
            frobnication portability. See
            <http://ruckford.example.com/>_ for details.

            """
        pass
        pass
        pass

I would be happy to see these conventions be more formalised; after all,
reStructuredText was originated as a means of formatting documentation
in Python docstrings.

-- 
 \        “All opinions are not equal. Some are a very great deal more |
  `\    robust, sophisticated and well supported in logic and argument |
_o__)                                     than others.” —Douglas Adams |
Ben Finney

[toc] | [prev] | [next] | [standalone]

#9506

Was tried at least once before:
http://www.python.org/dev/peps/pep-0287/

Check in here with your ideas:
http://www.python.org/community/sigs/current/doc-sig/

Have any other languages mandated the use of a specific documentation markup?

Michael

On Thu, Jul 14, 2011 at 7:02 PM, rantingrick <rantingrick@gmail.com> wrote:
>
> Hello Folks,
>
> Lately i have been musing over the ideas of method tagging.
> Specifically i am referring to method identifiers. As most of you know
> i had proposed to add "syntactical markers" to the language to deal
> with the ambiguities that arise whist eyeball parsing sub classed
> methods that clobber virtual methods. HOWEVER that idea caused some
> fierce controversy within the community, and i can partly understand
> why.
>
> Although i strongly believe in proper documentation (even to the point
> of forcing syntax on folks) i understand that we cannot implement such
> a thing without major growing pains. So with that being said, i have
> formulated a new battle plan to defeat this problem of ambiguity.
>
> Unlike most languages out there we have doc-strings; and do we realize
> how great this gift is? Sometimes i wonder because you folks should
> really be using them like they are going out of style!
>
> As we all know PEP 257 lays out some ground rules for documentation
> strings HOWEVER i feel this PEP did no go far enough. Too many folks
> are refusing to document properly and so i will take this time to
> hammer out a spec. I would like to comments for or against.
>
> ---------------------------------------
>  New Syntax Specification For Documentation Strings
> ---------------------------------------
>
> """ {DOC TAG HERE}: {MODULE_NAME|SHORT_SUMMARY_HERE}.
> {NEWLINE}
> {LONG_DESCRIPTION_HERE}
> {NEWLINE}
> Arguments: (if applicable)
>    {ARGUMNET_1} <{TYPE}>:
>        ARGUMENT_1_DESCRIPTION}
>    {ARGUMNET_2} <{TYPE}>:
>        ARGUMENT_2 DESCRIPTION}
>    {ARGUMNET_N} <{TYPE}>:
>        ARGUMENT_N_DESCRIPTION}
> {NEWLINE}
> """
>
> As you can see my spec introduces some new ideas to writing doc-
> strings. Specifically the "DOC TAG" and {ARG TYPES} are new. Also i've
> found it much more useful to separate args and their respective
> descriptions with a newline and indention.
>
> ---------------------------------------
>  Example: Module Documentation String.
> ---------------------------------------
>
> """Module <simpledialog.py>:
>
> This module handles Tkinter dialog boxes.
> It contains the following public symbols:
>
>    Dialog <class>:
>        A base class for dialogs.
>
>    askinteger <function>:
>        Get an integer from the user.
>
>    askfloat <function>:
>        Get a float from the user.
>
>    askstring <function>:
>        Get a string from the user.
>
> """
>
> I don't know how i feel about marking classes and functions since IF
> we follow the python style guide we don;t need to; but that's IF we
> FOLLOW it people, IF.
>
> ---------------------------------------
>  Example: Func/Meth Documentation String.
> ---------------------------------------
>
> def askinteger(parent, title, prompt, **kw):
>    """ Interface: Get an integer from the user.
>
>    Return value is an integer.
>
>    Arguments:
>        title <string>:
>            the dialog title
>        prompt <string|integer|float>:
>            the label text
>        **kw:
>            see SimpleDialog class
>
>
> ---------------------------------------
>  Example: Class Inheritance Documentation Strings.
> ---------------------------------------
>
> class Base():
>    def __init__(self):
>        """ Internal:"""
>        self.m1()
>
>    def m1(self, *args):
>        """Overide: """
>        pass
>
> class Derived(Base):
>    def __init__(self):
>        Base.__init__(self)
>
>    def _m1(self):
>        """ Internal: blah"""
>
>    def m1(self):
>        """ Clobbered: see Base for detail"""
>
>    def m3(self):
>        """ Interface: Blah"""
>
> ---------------------------------------
>  Tags For Documentation Strings
> ---------------------------------------
>
>  Module:
>    The module tag is to be used for module doc strings.
>
>  Virtual:
>    The virtual tag is for methods residing in a base class
>    that are created specifically to be overridden. Of course as we
>    all know every Python methods/function is virtual by default
>    however the point of this is to make the code more readable!
>
>  Override:
>    This tag should be placed in a derived class's method which has
>    clobbered a base method. Typically you can just defer the reader
>    to look up the base class for more info.
>
>  Internal:
>    This tag should be used on all internal methods (psst: the ones
> that
>    start with a single underscore *ahem* or SHOULD start with a
> single
>    underscore!).
>
>  Interface:
>    This tag is be used for interface method/function doc strings.
> This
>    is probably the most important tag. If you don't do any tagging AT
>    LEAST tag the interface methods and functions. However i must
>    remind you that all these tags are very important.
>
> --
> http://mail.python.org/mailman/listinfo/python-list
>

[toc] | [prev] | [next] | [standalone]

#9511

On Fri, Jul 15, 2011 at 9:02 AM, rantingrick <rantingrick@gmail.com> wrote:
> Too many folks
> are refusing to document properly and so i will take this time to
> hammer out a spec.

The tighter you squeeze your fist, Lord Rick, the more star
programmers will slip through your fingers.

Make it so docstrings HAVE to be in a particular format, and people
will stop writing docstrings. Make it so Python functions HAVE to have
docstrings, and people will stop writing Python functions.

ChrisA

[toc] | [prev] | [next] | [standalone]

#9560

On Jul 15, 2:13 am, Chris Angelico <ros...@gmail.com> wrote:
> On Fri, Jul 15, 2011 at 9:02 AM, rantingrick <rantingr...@gmail.com> wrote:
> > Too many folks
> > are refusing to document properly and so i will take this time to
> > hammer out a spec.
>
> The tighter you squeeze your fist, Lord Rick, the more star
> programmers will slip through your fingers.
>
> Make it so docstrings HAVE to be in a particular format, and people
> will stop writing docstrings. Make it so Python functions HAVE to have
> docstrings, and people will stop writing Python functions.

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.

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.

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.

[toc] | [prev] | [next] | [standalone]

#9578

On Sat, Jul 16, 2011 at 4:56 AM, rantingrick <rantingrick@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

[toc] | [prev] | [next] | [standalone]

#9624

On Jul 15, 6:16 pm, Chris Angelico <ros...@gmail.com> wrote:
> On Sat, Jul 16, 2011 at 4:56 AM, rantingrick <rantingr...@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

[toc] | [prev] | [next] | [standalone]

#9628

On Sun, Jul 17, 2011 at 1:32 AM, rantingrick <rantingrick@gmail.com> wrote:
> On Jul 15, 6:16 pm, Chris Angelico <ros...@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

[toc] | [prev] | [next] | [standalone]

#9652

-----BEGIN PGP SIGNED MESSAGE-----
Hash: RIPEMD160

On 2011.07.16 10:32 AM, rantingrick wrote:
> 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'
> 
>>>> 
Shouldn't that be s = s.replace('--->', '\t') ?

:p
- -- 
CPython 3.2.1 | Windows NT 6.1.7601.17592 | Thunderbird 5.0
PGP/GPG Public Key ID: 0xF88E034060A78FCB
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEbBAEBAwAGBQJOIhjWAAoJEPiOA0Bgp4/LdgYH+Mi1Fs5iUbwa77K7ta65WqG2
Ga1gOmqtD+wWn6NwM/5uFfCPhYVUbiGzr0J4BZn11SbmNEa7/ePKmg7F4C1ShJBe
CiZzKA2yhP2rkQzsvwExYSEJQi8Xdrx4qnyDRGyFBbolPFxugM2+pm1cghzgF6po
+meJQfpGNKvsgAWwxLLP2MRy10QHfKH6VdlIToMbgMtpQiEI2/qVBZWq5QZ6bMcG
9RMFMDUiEXSlWMhjenRPL9sc+9m5ZWgd6wSHDvCG0Dg7NRIIvdod8V+bvJIkLGln
PLC5h3Oq25l+YJI6opeEaXtD24SqI3MSmNIRQhNTKMLfe+owQCEGN7U50aQE/Q==
=wpRx
-----END PGP SIGNATURE-----

[toc] | [prev] | [next] | [standalone]

#9657

On Jul 16, 6:03 pm, Andrew Berg <bahamutzero8...@gmail.com> wrote:

> Shouldn't that be s = s.replace('--->', '\t') ?

Now you see what this four space "brain washing" has done to us!

[toc] | [prev] | [next] | [standalone]

#9660

On Sun, Jul 17, 2011 at 9:25 AM, rantingrick <rantingrick@gmail.com> wrote:
> Now you see what this four space "brain washing" has done to us!
>

At least we have clean, freshly-washed brains.

ChrisA

[toc] | [prev] | [next] | [standalone]

#9659

-----BEGIN PGP SIGNED MESSAGE-----
Hash: RIPEMD160

On 2011.07.16 06:12 PM, Chris Angelico wrote:
> He's on Steven's killfile, and he might get himself on mine.
He's like a guy at a party who's had too much to drink. He'll start
going on about conspiracy theories and philosophies based more on blood
alcohol level than deep thought, and if you try to argue with him,
you'll just get sucked down to his level. However, if you watch at a
distance and don't take anything he says seriously, it can be entertaining.

- -- 
CPython 3.2.1 | Windows NT 6.1.7601.17592 | Thunderbird 5.0
PGP/GPG Public Key ID: 0xF88E034060A78FCB
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEcBAEBAwAGBQJOIiJkAAoJEPiOA0Bgp4/LwrAH/iLn6Ru9zEBMVoJdKIuSgMHS
kZKNRD1C1FeCpAD3Ii6foVtEi/CyWvhL8DeHtrDtEoL86/KKWr9WZWmRzVGLOTlw
crv+X5muWBYb/ra10EbS8iZ2xBysnG66hItBQ6XorUTE3Ku4IUu3E2pJ69S1zCNc
iIUB227jeO7gi415mxbvRz+nSCiYLVuvois6QqdF7SQsDPR+6e/graQGeOpMl1Wa
7ZRRHoqPZfoYcObEhpzTXHoX7vA0fP86zrl50DUX2KEx/sIqvZyQzqV3vViqYN69
tCdfGbKKTq7zW0dKkB3PgNZNxBOx6Idna15SN4h3OsDqCft+zSXOBunwfcrlmOk=
=eY7W
-----END PGP SIGNATURE-----

[toc] | [prev] | [next] | [standalone]

#9645

Dodgy medium?  Such as?  I just avoid sending code over any medium
that is going to change the text in any way.  Are you sending it with
an instant messenger client or something?  There are lots of ways,
some very convenient, to transfer files without them being modified.
If you need to quickly share little snippets where an instant-message
type medium is tempting, perhaps try pastebin.com.

Michael

On Fri, Jul 15, 2011 at 7:16 PM, Chris Angelico <rosuav@gmail.com> wrote:
> tries his best to avoid Python if the code is going to be shared over any
> "dodgy medium" where indentation might be damaged.

[toc] | [prev] | [next] | [standalone]

#9671

Michael Hrivnak wrote:

> Dodgy medium?  Such as?  I just avoid sending code over any medium
> that is going to change the text in any way.  Are you sending it with
> an instant messenger client or something?  There are lots of ways,
> some very convenient, to transfer files without them being modified.
> If you need to quickly share little snippets where an instant-message
> type medium is tempting, perhaps try pastebin.com.

Some email clients tend to mess with code pasted directly in the editor
window. e.g. arbitrarily word wrapping lines, converting it to HTML,
folding whitespace, inserting a leading space to mask lines that start
with "from", changing the encoding, and other changes.

But I've never come across an email client that messes with attachments.
Just send your code as an attached .py file and it's all good.

However, blog and forum software, even those aimed at programmers, often do
an astonishingly crap job at not messing with your text.



-- 
Steven

[toc] | [prev] | [next] | [standalone]

#9693

On 07/16/2011 10:10 PM, Steven D'Aprano wrote:
> But I've never come across an email client that messes with
> attachments. Just send your code as an attached .py file and
> it's all good.

However I'm on a couple mailing lists (e.g. lurking on OpenBSD) 
that strip all attachments...

-tkc

[toc] | [prev] | [next] | [standalone]

#9724

On Jul 17, 6:11 am, Tim Chase <python.l...@tim.thechases.com> wrote:
> On 07/16/2011 10:10 PM, Steven D'Aprano wrote:
>
> > But I've never come across an email client that messes with
> > attachments. Just send your code as an attached .py file and
> > it's all good.
>
> However I'm on a couple mailing lists (e.g. lurking on OpenBSD)
> that strip all attachments...


If this IS true then format your source with "indentation-
markers" ("--->") and tell the receiver to run str.replace() on the
source. Also you should send a rant to the list owner concerning this
atrocious striping behavior.

But then again, you could just post it to a paste bin or email it to
group members directly.

[toc] | [prev] | [next] | [standalone]

#9654

On Sun, Jul 17, 2011 at 5:23 AM, Michael Hrivnak <mhrivnak@hrivnak.org> wrote:
> Dodgy medium?  Such as?  I just avoid sending code over any medium
> that is going to change the text in any way.  Are you sending it with
> an instant messenger client or something?  There are lots of ways,
> some very convenient, to transfer files without them being modified.
> If you need to quickly share little snippets where an instant-message
> type medium is tempting, perhaps try pastebin.com.

MUDs are kinda like IM systems only more... and less. It's a lot
easier to simply share the code directly. Going to pastebin or similar
means switching to the web browser; and quite a few people have used a
MUD while unable, for various reasons, to access the web (usually this
turns out to be a DNS issue, but not always). Anyway, I never said
that Python was permanently unsuitable, but it's nice when I don't
have to worry about formatting.

ChrisA

[toc] | [prev] | [next] | [standalone]

#9554

Em sexta-feira, 15 de julho de 2011 04:13:43, Chris Angelico escreveu:
> On Fri, Jul 15, 2011 at 9:02 AM, rantingrick<rantingrick@gmail.com>  wrote:
>> Too many folks
>> are refusing to document properly and so i will take this time to
>> hammer out a spec.
> 
> The tighter you squeeze your fist, Lord Rick, the more star
> programmers will slip through your fingers.
> 
> Make it so docstrings HAVE to be in a particular format, and people
> will stop writing docstrings. Make it so Python functions HAVE to have
> docstrings, and people will stop writing Python functions.
> 
> ChrisA

I'm with Chris. If you mandate this sort of things on the programmer 
this will just go downhill.

George

-- 
--------------------------------
George Rodrigues da Cunha Silva
Desenvolvedor GIS
http://geoprocessamento.net
http://blog.geoprocessamento.net

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web