To document functions in Python, use docstrings (triple quotation marks).
For example:
def greet(name):
""" Greets a person with their name. """
print(f"Hello, {name}")
But why is this better than a regular comment with #?
It is because you can then call the help() function on a method to see its documentation.
For example, if you now call:
help(greet)
You see this info about the function in the console:
Help on function greet in module __main__:
greet(name)
Greets a person with their name.
(END)
In this guide, you learn how to document Python functions using docstrings. You also learn how to use the built-in help() function to view the docs.
Python Help Function
Python has a built-in help() function. You can use it to get additional info about a function, method, or class.
For example, you can get information about the print() function using help:
>>> help(print)
This gives you a result of:
Help on built-in function print in module builtins:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
(END)
This is possible on any built-in type, module, class, or function. It can save you time as you do not have to separately search the web or the documentations.
This helpful information is actually known as a Python docstring. It is thus not a magical string that just pops up from somewhere.
Actually, you can document your own code this way too. Let me show you how.
Python Docstring—How to Document Your Code
A Python docstring is a documentation string.
When you call the built-in help() function on a Python class, function, or module you see its documentation. This documentation is specified by the docstring at the beginning of the definition.
This is something you can do in your projects too. Instead of leaving useless comments before defining a function, you can add a docstring inside of it.
Let’s see an example. Here we create a simple function and document it with the docstring.
def add(a, b):
""" sums up two numbers """
return a + b
If you now call help(add), you see the documentation you wrote:
Help on function add in module __main__:
add(a, b)
sums up two numbers
(END)
In reality, you usually want to write longer and more comprehensive documentation that is spread across multiple lines.
For example, a better way to document the add() function would be:
def add(a, b):
"""
Sum up two integers
Arguments:
a: an integer
b: an integer
Returns:
The sum of the two integer arguments
"""
return a + b
Now the documentation of this method is more descriptive. It is helpful for someone that calls the help() function on it:
help(add)
Output:
Help on function add in module __main__:
add(a, b)
Sum up two integers
Arguments:
a: an integer
b: an integer
Returns:
The sum of the two integer arguments
(END)
Tip: Escape the help view in Terminal by pressing Q on your keyboard.
Using a Docstring as a Multi-Line Comment in Python?
Python does not support multi-line comments. Instead, you should write consecutive single-line comments using the # operator.
But as you saw, you can break a docstring into multiple lines. So you could use a docstring as a multiline comment in Python:
"""
This is just a function
that sums up two numbers.
"""
def add(a, b):
return a + b
But this is an imperfect way to do it.
If you add a “comment” like this at the first line of a class, function, or module, you accidentally produce a docstring. This may not be what you want.
Conclusion
Today you learned how to document functions in Python.
A documentation string or docstring is a triple-quote string. It can be added to the first line of a function, class, or module. It acts as the documentation of that piece of code.
def greet(name):
""" Greets a person with their name. """
print(f"Hello, {name}")
A docstring is useful because you can call the built-in help() function on the documented code to see its documentation.
I hope you enjoy it!
Thanks for reading.
Happy coding!