Kortfattat om PEP 257

Denna sida pekar ut särskillt relevanta delar av PEP 257 och är tänkt att hjälpa er komma igång med PEP257. Ni bör självklart även läsa riktiga referensdokumentet: https://peps.python.org/pep-0257/

Alla markeringar i fetstil är tillagda för att hjälpa läsaren och finns inte i referensdokumentet.

Docstrings

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition.

All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings.

Docstrings som skrivs som en rad

• The closing quotes are on the same line as the opening quotes. This looks better for one-liners.
• There’s no blank line either before or after the docstring.
• The docstring is a phrase ending in a period. It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.

Exempel från PEP257:

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

Docstrings över flera rader

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.

Dokumentation av ett skript

The docstring of a script (a stand-alone program) should be usable as its “usage” message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a “-h” option, for “help”).

För en funktion/metod

The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

Exempel från PEP257:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...