Understanding Python Docstrings and Their Purpose

00:00 As you know, docstrings are a way to document your modules, classes, and functions. The standard for Python docstrings is defined in Python Enhancement Proposal, or PEP 257.

00:11 PEPs are the official way for the Python community to propose improvements and standards for the Python programming language, guiding its development. PEP 257 is titled Docstring Conventions, and it covers their structure and content.

00:23 It tells you what a docstring should do and lays out general conventions, but what it doesn’t do is give a strict prescription for how you must write them.

00:32 In fact, multiple styles of docstrings exist, and you’ll look at some of the major ones in Python, including Google, NumPy, and reStructuredText formats.

00:41 One of the benefits of using a particular style of docstring is that you can even use tools like Sphinx that can automatically generate documentation from your docstrings.

00:51 Ultimately, at a high level, docstrings should provide clear, consistent documentation that helps users understand your code.

00:58 Now for some technical details.

01:01 A valid docstring in Python is a string literal enclosed in triple double quotes. That’s a requirement. They should be double quotes, and there has to be three of them.

01:10 It must be the first statement of a module, class, or function to be considered a docstring. However, it can be either one line or span across multiple lines, and most importantly, it should document the behavior and usage of the code.

01:25 I hope that’s not surprising. So what does an actual docstring look like? Let’s see a couple examples. On the left, you have a single-line docstring, and this is fine for a simple, straightforward function.

01:37 def determine_magic_level() with the parameter age, and the docstring: """Multiply wizard's age by three to reveal their magic level""", with the functionality of simply returning age * 3.

01:48 The docstring is concise and provides a summary of the function’s behavior, and note that the opening and closing quotes are on the same line. This is preferred for single-line docstrings according to PEP 257.

02:00 Now, examine the function on the right with a multi-line docstring: def get_harry_potter_book() with the parameters publication_year and title, and a docstring: Retrieve a Harry Potter book by its publication year and name.

02:11 Parameters: publication_year (int): the year the book was published. title (str): the title of the book. Returns a string, a sentence describing the book and its publication year, with the functionality: return the f-string, f"The book {title} was published in {publication_year}." It still starts with a one-line summary of the function’s behavior, which is also suggested by PEP 257, followed by a blank line and more detailed information.

02:37 In this case, it includes parameters and return value with type information and descriptions. And because it’s a multi-line docstring, the closing quotes should be on a new line, also recommended by the PEP.

02:50 And now that you’ve seen this much, you might be thinking this sounds a lot like code comments. And while they may seem similar, there are some key differences to consider.

03:00 The first is syntax. Comments begin with a pound sign, a number sign, hash. You know what I mean. While docstrings are enclosed in triple double quotes, their function is also distinct.

03:14 Comments are for leaving notes for developers who are working with the code directly, while docstrings serve primarily as documentation for users and tools, which is why comments are ignored by the Python interpreter entirely, where docstrings are actually part of your programs and stored in the __doc__ attribute, accessible at runtime.

03:32 Finally, comments can be placed anywhere in your code, and as you know, docstrings must be placed at the start of your modules, classes, and functions.

03:42 Ultimately, in Python, comments don’t replace docstrings and vice versa. They’re complementary techniques that each serve a different purpose. And since I mentioned that one of the unique things about docstrings is that they’re accessible at runtime, let’s take a look how in the next lesson.