If you are new to Python and ever feel lost or have a question about a particular function or feature of Python, the best place to look is the Python docstrings. You may wonder what is this function and why you might want to include one in your code. Python docstrings is a powerful tool that can help you document your code more effectively. By providing human and machine-readable information, docstrings make it easy to understand and debug your code.
In this article, we will take you through the basics of docstrings for a simple function and explain some of the benefits of using docstrings. Furthermore, explain why they are such a valuable resource for developers. Ready to learn more? Let us get started.
Table of Contents
What is Python Docstrings ?
Docstrings are a helpful way to document the functions, modules, classes, and methods of your Python code. For example, other developers can use Docstrings when they need to understand how an API or module works or when they want to write custom applications that use this code.
Advantages of Python Docstrings
Python docstrings are very important in developing and debugging Python code. Docstrings are a sequence of strings that are automatically generated for every function, class, or module in a program. It is a brief, descriptive comment associated with the source code of a program. It can be used for two purposes: to document the function or object in question and to provide instructions, such as its name and arguments, on how to use it.
Docstring Format
| Formatting Type | Description |
|---|---|
| Google docstring | This type of documentation is recommended by google. |
| reStructuredText | This type of documentation is Python’s official but is not friendly for beginners. |
| NumPy / SciPy docstring | This type of documentation is a mix of Google docstring and reStructured text. |
| EpyText | This type of documentation is an adaptation of python. |
One-Line Docstring in Python
Python has an exciting feature called docstrings, which allows you to include them in your code files for easy reference. A one-line docstring contains single-line text, and the closing quotes must be the same as the opening. This helps to document the function’s purpose and provides additional information about the module or class.
Let’s have a look on the below code snippet for better understanding,
import math
print (math.factorial(5))
print (math.factorial.__doc__) Output
Find x! Is a reStructured text docstring.
Multi-line Docstring in Python : built-in help() Function
A multi-lined docstring is a document string that contains multiple lines of text. It can be used to add extra information or context to your documents, and it makes them easier to read. It allows you to insert paragraphs, headers, subheadings, and other related elements into your document without having to break it up into multi-line strings. This feature should not be confused with the header section of a document, which includes only one line of text.
A good way to format a multi-lined docstring is by starting on a newline character and then inserting each successive sentence on its own separate line.
By using the built-in function help() we have generated a multi-line docstring for print function,
help(print) Output
Python Docstring Using Class : built-in doc Attribute
The class docstring is a single-line text string. The built-in doc functions in Python allow you to execute code dynamically, which can be helpful when developing scripts. For example, creating a class, we have printed the docstring (NumPy/ SciPy) in the following code snippet.
Let us have a look at the below code example to understand how NumPy/SciPy docStrings are:
import math
class factorial:
"""
This is a class to calculate the factorial of a given number.
"""
print (math.factorial(5))
print (factorial.__doc__)
# accessing the docstring for class
print (math.factorial.__doc__)
# accessing docstring for import file math Output
Comment vs Docstring
Docstring and comment are two different types of comments in Python. Docstring is a documentation string that you include at the beginning of your module, function, or class. It should hold minimal information and should be concise.
Comment is used for longer-form explanations or notes related to the code itself. Comments can range from simple remarks about how a block of code works to more involved discussions about design decisions or architecture principles. They are evaluated by the compiler just like other code blocks, so it’s important that they’re written correctly and free of errors.
FAQs
What should be in Docstrings?
They can include any information you feel is necessary for readers to understand your content quickly and easily. In addition, you should ensure that all relevant information is included in the docstrings, so there is no extraneous clutter below.
Are docstrings only for function?
No, docstrings can be used for either function or presentation. However, they are typically used for presentation because they allow you to document your code in a more concise and easy-to-read manner. They also help to keep your code organised and improve the readability of your project.
Is docstring optional in python?
Docstrings are a useful way to document the functions and methods of a program. They can be used to make the code more self-explanatory. Docstrings are also optional in python you don’t need to include them if you don’t want to.
Python string method is a unique function that allows you to manipulate strings, learn more about them, and go through with the article Python String interpolation.
Conclusion
This blog explored how Python docstrings help write clear and understandable code. The best part about code in Docstrings is that they are fully expandable and customizable. The next time you need to write a new function or module in your Python code, make sure it has a docstring first. As long as you write meaningful Docstrings, it will go a long way in helping to understand the logic behind your code. I hope this article will help you to understand the docstring more clearly. Thanks for reading.
