4.1 PEP 257 – Docstring Conventions

Aquesta és una revisió antiga del document —-

PEP 257 is a document created as part of the Python Developer's Guide, which makes an attempt to standardize the high-level structure of docstrings. It outlines the conventions, best practices, and semantics (not laws or regulations!) associated with documenting Python code using docstrings. In short, it tries to answer the following two questions:

What should Python docstrings contain?
How should Python docstrings be used?

A docstring is «a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the doc special attribute of that object.» (PEP 257)

In other words, docstrings are Python documentation strings that are used in the class, module, function, and method definition in order to provide information about the functionality of a larger piece of code in a prescriptive way.

They help programmers (including you) to remember and understand the purpose, operation, and capabilities of particular code blocks or sections.

Docstring vs. comments

Before we move on, we need to understand this essential distinction (as their names suggest): comments are used for commenting your code, while docstrings are used for documenting your code. So, what is the difference between comments and docstrings, and eventually between commenting and documenting code?

Look at the table below, where we want to show you some of the differences between comments and docstrings in Python:

Comments	Docstrings
Comments are non-executable statements in Python, which means that they are ignored by the Python interpreter; they are not stored in the memory, and cannot be accessed during program execution (i.e. they can be accessed by looking at the source code).	Docstrings can be accessed by reading the source code, and by using the `doc` attribute or the `help()` function.
The main purpose of comments is increasing the readability and understandability of the code, and explaining the code to the user in a meaningful way. The user here means both other programmers and you (e.g. when you go back to your code after some time) – somebody who will want to or need to modify, extend, or maintain the code.	The main purpose of docstrings is documenting your code – describing its use, functionality, and capabilities to users who do not necessarily need to know how it works.
Comments cannot be turned into documentation; their purpose is to simplify the code, provide precise information, and help to understand the intention of a particular snippet/line.	Docstrings can be easily turned into actual documentation, which describes a module's or function's behavior, the meaning of parameters, or the purpose of a specific package.

Of course, as you'll see in the next pages, there's much more that we want to tell you about docstrings: how to use them, why use them, and where; and – as you expect – the difference between comments and docstrings will become even more evident.

Why comment? Why document?

Before we delve into the topic of docstrings, let's try to answer the question: why is commenting and documenting code important?

Essentially, we must not forget this simple rule by Guido van Rossum: «Code is more often read than written», which basically means that the code we write today will most likely be read in the future – either by you, or by another programmer, or even teams of programmers.

It is therefore crucial that we develop such programming and code writing habits that will allow the developers and other users to understand the code's whys and hows, as this will make the reusing of and contributing to code much easier.

So, we should agree that documenting code helps to maintain a cleaner, more readable, and more sustainable code, which means it's one of the best practices a good, responsible developer should adopt as part of their daily programming workshop toolset.

A quick recap of comments

We hope that you remember that comments in Python are created using the hash sign (#). They should be rather brief (no more than 72 characters per line), begin with a capital letter, and end with a full stop.

If you need to include a longer comment in your code, you can use a multiple-line comment, in which case you should use the hash sign at the beginning of each line of comment.

Generally, you should insert comments close to the code you're describing in order to make it clear for the reader which part of the code you're referring to. You should be precise – don't include irrelevant or reduntant information; and most of all – try to design and write your code in such a way that it easily and comprehensibly comments itself (e.g. give self-commenting names to variables).

When use comments?

Apart from the most obvious cases, such as code and algorithm descriptions, comments may serve a few other useful purposes. For example:

they can help you tag those sections of code that are to be done in the future, or are left for further improvement, e.g.:

# TODO: Add a function that takes the val and prc arguments.

they can help you comment (and uncomment) those sections of code that you want to test, e.g.:

def fun(val):
    return val * 2
 
user_value = int(input("Enter the value: "))
# fun(user_value)
# user_value = user_value + "foo"
 
print(fun(user_value))

they can help you plan your work and outline certain sections of code that you will be designing, e.g.:

# Step 1: Ask the user for the value.
# Step 2: Change the value to an int and handle possible exceptions.
# Step 3: Print the value multiplied by 0.7.

Before we move on from talking about comments to elaborating on docstrings, there is one more Python feature that we want to briefly tell you about – type hinting.

Type hinting is a mechanism introduced with Python 3.5 and desecribed in PEP 484 that allows you to equip your code with additional information without using comments. It's an optional, but more formalized, feature that makes it possible for you to use the Python built-in typing module to provide type hint information in your code in order to leave certain suggestions, mark certain possible problems that may come up in the development process, and label specific names with type information.

In a nutshell, type hinting allows you to statically indicate the type information related to Python objects, which means that you can, for example, add type information to a function – indicate the type of an argument the function accepts, or the type of the value it will return. Look at the following examples: