undo 'autopep8' removal of pep-257

[cjbayliss]

I don't know if 'autopep8' incorrectly ignored pep-257, or if I manually messed up the one-line docstrings. Either way, this reverts back to pep-257 docstrings.

[alexlance]

You can do single-quote docstrings with python3 I think - maybe they would be nicer? No dramas either way. Eg:

def delete_sqs_item(url, receipt):
    'Manually delete item from an SQS queue'
    if receipt:
        <snip>

[cjbayliss]

So it would seem there is a little bit of controversy about docstrings, the people I asked are rather opinionated. Some say they should be formatted like so:

# this is a docstring
def foo():
    print('bar')

but that won't work with print(repr(foo.__doc__)). but it will work with help() under certain circumstances.

Then there is the format you suggested:

def foo():
    'this is a docstring'
    print('bar')

This looks the nicest to me, however: it's not liked by others. I was presented with no argument other than "It's wrong".

I conclude that is would be safest and least controversial to use """this is a docstring""". We would have the backup of PEP 257 for it too:

For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""".

---

Just to note, I thought I was doing a good thing by reverting to PEP 257 docstrings, but now I'm questioning myself. 😕

---

Right, with this information, what do you think is the best way forward @alexlance? I'm easy going. 🙂

[alexlance]

I don't really see any problem with either style - provided it is followed consistently through the project.

Triple-quotes appear to have greater usage than single-quote. Happy to leave this with you. :grin:

[cjbayliss]

Triple-quotes appear to have greater usage than single-quote. Happy to leave this with you. 😁

Haha, ok. I'll merge this then.

---

For future reference, I'm of the opinion 'docstring' is nicer for these two reasons:

• it is subjectively prettier.
• it is faster to type' than """
• it reminds me of scheme/lisp (pointless I know)

And the reason I'm going with """docstring""" is:

• PEP 257
• it is the most used and accepted format for docstrings in python projects

[cjbayliss]

Oh great. I just made a mistake. For some reason I thought you had put an approve tag on this merge. But now I see it hasn't been reviewed by anyone. 😕

Could you please review it anyway? If there is problems I'll make the needed fixes. I'm really sorry about this 😞 In the future I'll double check.