What is docstring in Python with examples?


You may have seen docstrings in Python before, but what exactly are they? In this blog post, we’ll take a look at what docstrings are and why they’re useful. We’ll also explore how to write your own docstrings and see some examples of good and bad docstrings. By the end of this post, you should have a good understanding of what docstrings are and how to write them effectively.

What is a Docstring?

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

Python’s documentation conventions recommend that docstrings be enclosed in triple quotes (“””), although single quotes (”) will work as well.

They are used to provide documentation for users of the code, as well as for automated documentation tools like Sphinx.

An example function

def func(): """This is a function that does nothing at all""" return
Code language: Python (python)

The docstring can be accessed using the __doc__ attribute:

print(func.__doc__) #Output: This is a function that does nothing at all
Code language: Python (python)

The purpose of a docstring is to document the code so that other programmers can understand it more easily. Good docstrings contain such important information as the purpose of the code, the author’s name, the date written, and any copyright notice.

They can also contain helpful information for users of the code, such as usage examples. However, not all docstrings are created equal; some are quite helpful while others are barely better than no documentation at all. Let’s take a look at some examples.

Example 1: Bad Docstring

This function prints “Hello, world!” to the screen.

print("Hello, world!")
Code language: PHP (php)

This docstring is short, but it’s not very informative. It doesn’t tell us what the function does or why someone might want to use it. It also doesn’t give any usage examples. Overall, this is not a very good docstring.

Example 2: Good Docstring

This function prints “Hello, world!” to the screen.

print("Hello, world!") # prints "Hello, world!" on its own line
Code language: PHP (php)

This better docstring contains more information than Example 1; it tells us what the function does and gives us a usage example. It’s still pretty short, though, so there’s room for improvement (we’ll see how in just a moment).

import os # for os.listdir() # for shutil.copyfile() # copies files from one directory to another def copy_files(src_dir, dest_dir): """Copy all files from src_dir to dest_dir.""" pass
Code language: Python (python)

Now we’re getting somewhere! This last example contains all of the important information that should be included in a docstring: author information, copyright notice, usage examples, etc. Furthermore, it uses blank lines and indentation to make the docstring more readable. This is an excellent example of a well-written docstring.

A function would be documented like this using the Sphinx/reStructuredText format:

def hello(name, language="en"): """Say hello to a person. :param name: the name of the person :type name: str :param language: the language in which the person should be greeted :type language: str :return: a number :rtype: int """ print(greeting[language]+" "+name) return 4
Code language: Python (python)

A function would be documented like this using the Google Style Guide format:

def hello(name, language="en"): """Say hello to a person. Args: name: the name of the person as string language: the language code string Returns: A number. """ print(greeting[language]+" "+name) return 4
Code language: Python (python)

Conclusion:

Docstrings are an important part of programming in Python (or any language for that matter). A well-written docstring can save you time by providing clear and concise documentation for your code so that you don’t have to keep referring back to your source code every time you forget how something works.

Docstrings can also save you time by helping you remember why you wrote certain code in the first place. Writing good docstrings takes practice but it’s worth taking the time to learn how to do it correctly; your future self will thank you!

Andy Avery

I really enjoy helping people with their tech problems to make life easier, ​and that’s what I’ve been doing professionally for the past decade.

Recent Posts