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

Search Discussions

  • Ben Finney at Jul 15, 2011 at 12:24 am

    rantingrick <rantingrick at 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
  • Michael Hrivnak at Jul 15, 2011 at 6:00 am
    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 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
  • Chris Angelico at Jul 15, 2011 at 7:13 am

    On Fri, Jul 15, 2011 at 9:02 AM, rantingrick 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
  • George Rodrigues da Cunha Silva at Jul 15, 2011 at 3:44 pm

    Em sexta-feira, 15 de julho de 2011 04:13:43, Chris Angelico escreveu:
    On Fri, Jul 15, 2011 at 9:02 AM, rantingrickwrote:
    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
  • Rantingrick at Jul 15, 2011 at 6:56 pm

    On Jul 15, 2:13?am, Chris Angelico wrote:
    On Fri, Jul 15, 2011 at 9:02 AM, rantingrick 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.
  • Chris Angelico at Jul 15, 2011 at 11:16 pm

    On Sat, Jul 16, 2011 at 4:56 AM, rantingrick 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
  • Michael Hrivnak at Jul 16, 2011 at 7:23 pm
    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 wrote:
    tries his best to avoid Python if the code is going to be shared over any
    "dodgy medium" where indentation might be damaged.
  • Chris Angelico at Jul 16, 2011 at 11:09 pm

    On Sun, Jul 17, 2011 at 5:23 AM, 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.
    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
  • Steven D'Aprano at Jul 17, 2011 at 3:10 am

    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
  • Tim Chase at Jul 17, 2011 at 11:11 am

    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
  • Rantingrick at Jul 17, 2011 at 5:30 pm

    On Jul 17, 6:11?am, Tim Chase 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.
  • Rantingrick at Jul 16, 2011 at 3:32 pm

    On Jul 15, 6:16?pm, Chris Angelico wrote:
    On Sat, Jul 16, 2011 at 4:56 AM, rantingrick 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
  • Chris Angelico at Jul 16, 2011 at 4:25 pm

    On Sun, Jul 17, 2011 at 1:32 AM, rantingrick wrote:
    On Jul 15, 6:16?pm, Chris Angelico 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
  • Andrew Berg at Jul 16, 2011 at 11:03 pm

    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
  • Andrew Berg at Jul 16, 2011 at 11:44 pm

    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
  • Rantingrick at Jul 16, 2011 at 11:25 pm

    On Jul 16, 6:03?pm, Andrew Berg wrote:

    Shouldn't that be s = s.replace('--->', '\t') ?
    Now you see what this four space "brain washing" has done to us!
  • Chris Angelico at Jul 16, 2011 at 11:45 pm

    On Sun, Jul 17, 2011 at 9:25 AM, rantingrick wrote:
    Now you see what this four space "brain washing" has done to us!
    At least we have clean, freshly-washed brains.

    ChrisA

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
grouppython-list @
categoriespython
postedJul 14, '11 at 11:02p
activeJul 17, '11 at 5:30p
posts18
users8
websitepython.org

People

Translate

site design / logo © 2022 Grokbase