Docstring Style

[dbrgn]

What docstring style should we use?

My currently favorite style is:

"""
Start on second line, provide a short description of the entire code.

Add more details here. This may contain examples, links, explanations, reasons, etc.

Document the arguments here. End with an empty line.

"""

And:

"""
If the docstring is a one-liner, leave away the trailing empty line.
"""

For the docstring style we could use Sphinx syntax to be able to generate parseable documentation.

[doismellburning]

fwiw my favourite is "whichever some highly-regarded Python linty thing uses" /cc @ghickman

[hashbangstudio]

"whichever some highly-regarded Python linty thing uses" 👍

[dbrgn]

There's no clear standard, as far as I know. The PEP regarding docstrings does not describe all the details.

[doismellburning]

:(

[doismellburning]

@ghickman-as-a-Service? ;P

[ghickman]

PEP257 should cover everything.

One line:

"""Simple one line docstring."""

Multi-line:

"""
Short summary like a subject line.

More in depth body of the docstring, giving more information and possibly
even a basic example.
"""

Ideally docstrings are limited to 78 characters since they are prose but I don't feel this needs to be a hard limit.

[doismellburning]

Yay PEP257. Do you have an automated enforcer handy?

[ghickman]

I don't unfortunately…

[dbrgn]

PEP257 is vague on various things. E.g. it specified that single-line docstrings are possible, but not that they can't stand on their own line, or which one is better. Rather it explains what a docstring is, what it should contain and how it should be parsed.

I'd vote for simply showing a few good examples. On the one line docstring thing I don't have a big preference, but usually I'd go for consistency (always starting on the second line). Also makes conversion from one style to the other unnecessary once someone adds more content to the docstring.

[ghickman]

One-liners are for really obvious cases. They should really fit on one line.

This seems pretty simple to me ;)

But I would agree with everything you say nonetheless, especially putting the single line docstring on a newline. Clean diffs are always better than the alternative.

For multiline docstrings I find Tim Pope's guide to git commits can be very useful on how to separate the "subject" and "body".

How's this?

One line:

"""
Simple one line docstring.
"""

Multi-line:

"""
Short summary like a subject line.

More in depth body of the docstring, giving more information and possibly
even a basic example.
"""

[doismellburning]

+1

[dbrgn]

Yes, that part is obvious. The question is whether we want a trailing empty line (useful to separate the docstring visually from the following function definition, as according to some PEP IIRC the code should follow the """ directly), or whether to use Sphinx style argument docs (and other directives).

[ghickman]

Personally I prefer no line between the docstring text and the """ and a blank line after. However this is a personal preference so if there was overwhelming consensus another way I'd be happy with that.

[doismellburning]

@dbrgn Can you clarify what "[t]he question is" please? I've revisited this issue trying to understand where we're at, and I confess to having no idea what's actually being debated...

[dbrgn]

Format / Whitespace:

"""
Short summary like a subject line.

More in depth body of the docstring, giving more information and possibly
even a basic example.
"""

code_starts_here = 1

vs

"""
Short summary like a subject line.

More in depth body of the docstring, giving more information and possibly
even a basic example.

"""
code_starts_here = 1

I'd vote for the latter.

Single line docstrings

"""Short docstring."""

vs

"""Short docstring.
"""

vs

"""
Short docstring.
"""

I'd vote for the last example. If a docstring is extended, we have cleaner git diffs.

Argument docs

"""
Sphinx-style docstring.

More in depth body of the docstring, giving more information and possibly
even a basic example.

:param height: The height of the block.
:type height: int
:param width: The width of the block.
:type width: int
:returns: A special type instance.
:rtype: :class:`package.module.SpecialType`

"""

vs

"""
Google-style docstring.

More in depth body of the docstring, giving more information and possibly
even a basic example.

Args:
    height (int):
        The height of the block.
    width (int):
        The width of the block.

Returns:
    A ``ackage.module.SpecialType`` instance.

"""

vs some other formats like Epydoc.

For non-library software I usually prefer the Google-Style docstrings, as they're easily readable. But for libraries I'd go with Sphinx-Style, so we could auto-generate API docs.

[doismellburning]

@dbrgn <3 thanks for clarifying!

[doismellburning]

(1/3/same-as-you here)

[pozorvlak]

1, 1 or 3, don't care here.

On Sun, Oct 19, 2014 at 11:24 AM, Kristian Glass [email protected]
wrote:

(1/3/2 here)

—
Reply to this email directly or view it on GitHub
https://github.com/py3minepi/py3minepi/issues/33#issuecomment-59645493.

[ghickman]

I've been pointed to a docstring checking tool, pep257 and a flake8 wrapper for it (thanks @meshy!).

Some error codes I'm not sure about:

D100: seems overkill to do this for every module.
D200: I still agree with your point earlier so torn here.
D20{3,4}: overkill on whitespace in classes to me.

re examples: 1, 1/3, don't mind

[doismellburning]

@ghickman Whack it in a PR with vanilla settings, see how it goes?

[meshy]

Pleasure :)

[dbrgn]

Wow, pep257 is nice :)