What Are Docstrings in Python?

A docstring is a string literal that you place as the first statement inside a function, a class, or a module. It becomes the __doc__ attribute of the object, so it is still available while the program is running instead of being thrown away by the interpreter.

import inspect


def area(width, height):
    """Return the area of a rectangle.

    Args:
        width: the width in metres.
        height: the height in metres.

    Returns:
        The area in square metres.
    """
    return width * height


print(area(3, 4))               # 12
print(area.__doc__)
print(area.__name__)
print(inspect.getdoc(area))

The printed docstring is the whole text of the literal, including the indentation of the continuation lines, so the raw __doc__ output looks ragged. That is exactly why inspect.getdoc exists. It cleans the indentation up and returns a properly formatted block, and that is what the documentation tools use.

There are three points to make in an interview. First, the docstring must be the very first statement, because a docstring placed after any other statement is just an unused string expression and the __doc__ attribute will be None. Second, it is not a comment, because it survives into the compiled bytecode and it can be read by help(), by doctest, and by the documentation generators. Third, the triple-quoted form is only needed because docstrings usually run over several lines. A one-line docstring can use ordinary quotes.

The convention for a multi-line docstring is that the closing triple quote goes on a line of its own, which is why the indented Args and Returns sections above line up the way that they do.

It reports None, because without a docstring there is no string to attach, and Python uses None for the attribute.

def undocumented(value):
    return value * 2


print(repr(undocumented.__doc__))    # None
print(undocumented.__name__)         # undocumented


class AlsoUndocumented:
    pass


print(repr(AlsoUndocumented.__doc__))     # None

The first line prints None, and the second line shows that the name attribute of the function is not affected by this. The class shows the same thing, because a class without a docstring has a __doc__ of None as well.

There are two practical notes here. First, notice that the example uses repr rather than print. print would output the word None, but repr shows it as a value, which makes it obvious that you are looking at an attribute and not at a printed message. That distinction matters when you are checking whether something is an empty string or a missing value.

Second, it is easy to test whether a docstring is there, and that test is how help() and the documentation tools decide whether to print a description at all. A tool that finds __doc__ set to None simply shows the signature and nothing else.

Some style checkers treat a missing docstring on a public function or class as an error. The pydocstyle tool and the matching rules in ruff exist for exactly this reason, and it is a common convention in libraries rather than in ordinary application code.

PEP 257 is the reference for Python docstring conventions. The short version is that a docstring should be a complete sentence that describes what the object does, that it should fit on one line if that is possible, and that a multi-line docstring should have a summary line, then a blank line, and then the details, with the closing quotes on a line of their own.

The section conventions are not set by the language itself, but two styles dominate. The Google style uses indented sections with the names Args, Returns, Raises, and Yields. The NumPy style uses underlined section names such as Parameters and Returns with a ruled line beneath them. Both of them are widely understood, because Sphinx, mkdocs, and the editors all recognise them.

As for the tools, there are several layers to know about. help() reads __doc__ at the interactive prompt, and pydoc generates browsable HTML documentation from the same place. Sphinx builds API documentation and understands both of the section conventions. doctest looks for examples inside docstrings and runs them as tests, which is why a wrong docstring example becomes a failing test. pydocstyle and the matching ruff rules check the conventions themselves, and editors such as VS Code and PyCharm show the docstring as a tooltip the moment you hover over a function.

There are two pieces of practical advice for interviews. Write the summary line first, because that is the line that people read, and if it is not clear then the rest will not be either. And keep the examples runnable, because doctest will fail the build if they drift out of date. That makes docstrings a genuinely useful test surface instead of decoration.