DEV Community

Kelechi Kizito Ugwu
Kelechi Kizito Ugwu

Posted on

Python Docstrings

In Python, if we do not assign a variable to a string, it acts as a comment named docstring.
They are string literals that appear right after a function, module or class. They are enclosed in triple quotes.
Docstrings are built-in strings that, when configured correctly, can help your users and yourself with your project’s documentation.

Docstrings Purposes
Their purpose is to provide users with a brief overview of the object(functions, modules, classes or scripts). At a bare minimum, a docstring should be a quick summary of whatever is it you’re describing and should be contained within a single line. Beyond the summary, multi-lined docstrings are used to elaborate on the object. The following are parts of a multi-lined docstrings:
A one-line summary line (picture)
A blank line proceeding the summary
Any further elaboration for the docstring
Another blank line

The maximum length of docstrings 72 characters.

Docstrings are divided into the following categories:
Class Docstrings
Package and module Docstrings
Script Docstrings

Class Docstrings are used for class and class methods. The docstrings are placed immediately following the class or class method indented by one level:

Package and module Docstrings are placed at the top of the package’s file. This docstring should list the modules and sub-packages that are exported by the package.

Scripts are single file executables run from the console. Docstrings in a script are placed at the top of the file and documented well for users to have sufficient understanding on how to use the script.

Top comments (0)