Essential Guidelines for Writing Docstrings in Python
Written on
Please, I urge you to write docstrings!
The 5 Essential Guidelines for Crafting Docstrings in Python
Are you also a proponent of the Zen of Python? I certainly am! You can easily access it by running a simple command: import this. Among its notable messages, one stands out: your code should be clear and “self-documenting.”
In this article, I will delve into the concept of self-documenting code and provide a set of essential guidelines for writing docstrings for your functions. At the end, I will present an exemplary function that calculates volume based on three inputs, complete with a thorough docstring.
>>> import thisThe Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one -- and preferably only one -- obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than right now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Self-Documenting Code (An Elusive Ideal)
“Self-documenting code” is a term frequently mentioned in programming discussions. The idea is straightforward: write your code in a manner that it elucidates its own functionality.
- While this is a goal all developers should strive for, there are instances when it falls short.
- This is where docstrings come into play!
Docstrings, or documentation strings, act as comments that clarify what your code (a module, function, class, or method) accomplishes. One of the remarkable features of docstrings is their compatibility with Python’s built-in help() function, which provides a straightforward reference guide for your code.
Unfortunately, docstrings are often neglected. Let’s change that!
Here are five essential guidelines for writing docstrings in Python:
- Enclose docstrings in triple quotes.
- Begin with a concise summary.
- Include a section for arguments.
- Include a section for return values.
- Clarify any potential exceptions raised.
Enclose Docstrings in Triple Quotes
Always use triple double quotes (""") around your docstrings. This signals to Python that the enclosed text is a docstring.
def greet(name):
"""This function greets the person passed in as a parameter."""
print(f"Hello, {name}!")
Start with a Simple Summary
The first line of your docstring should succinctly summarize the function's purpose. This line should be both brief and informative.
def multiply(a, b):
"""Return the product of two numbers."""
return a * b
Include an Arguments Section
If your function accepts parameters, describe each one, mentioning its name, type, and purpose, typically in the “Args:” section of the docstring.
def is_even(number):
"""
Check if a number is even.
Args:
number (int): The number to check."""
return number % 2 == 0
Include a Returns Section
If your function returns a value, describe it in the “Returns:” section. Include the type of the returned value and a brief explanation.
def calc_vol(l, w, h):
"""
Calculate the volume of a three-dimensional object.
Args:
l (float): The length of the object.
w (float): The width of the object.
h (float): The height of the object.
Returns:
float: The volume of the object, calculated as l * w * h."""
return l * w * h
Explain Potential Raise Statements
If your function raises exceptions based on certain conditions, clarify the reasons and the circumstances under which they are raised in the “Raises:” section. This is particularly useful for those who may want to implement exception handling when invoking your function.
def calc_vol(l=None, w=None, h=None):
"""
Calculate the volume of a three-dimensional object.
Args:
l (float): The length of the object. Defaults to None.
w (float): The width of the object. Defaults to None.
h (float): The height of the object. Defaults to None.
Returns:
float: The volume of the object, calculated as l * w * h.Raises:
TypeError: If l, w, or h are None or not numbers."""
if l is None or w is None or h is None:
raise TypeError("l, w, and h must be numbers, not None")return l * w * h
As promised, the calc_vol() function serves as an excellent illustration of a function that computes volume based on three parameters and includes a comprehensive docstring.
Bonus Tips
- Create a template docstring for your personal use. If you are part of a team, consider incorporating a docstring template into your team's reference materials or wikis.
- For quality templates, look at the docstrings from reputable libraries like Pandas, SciKit-Learn, Seaborn, and NumPy. Their well-crafted docstrings can serve as excellent examples.
- If you're producing tutorials, guides, and instructional content online, don't overlook the importance of docstrings. While it may seem repetitive, a well-written docstring can significantly enhance the value of the code you share.
Conclusion
As we navigate the expansive field of Python programming, particularly in data science, machine learning, and artificial intelligence, our interactions are often shaped by the code we work with and produce. Code serves as our medium for transforming intricate ideas into actionable solutions. However, code devoid of context can be as perplexing as a narrative without words. This is where Python docstrings come into play, illuminating our path toward understanding.
Python’s docstrings function as built-in guides for your code. They articulate what is occurring, why it’s happening, and how it unfolds. They are vital in making Python a favored choice for both novice data scientists and experienced AI practitioners. As we explore machine learning algorithms or identify patterns in large datasets, docstrings help document our processes, making our work clear and comprehensible to ourselves and others.
Writing quality docstrings is a skill and a practice that every data scientist and AI enthusiast should nurture. While engaging with Python libraries like NumPy, Pandas, Scikit-Learn, TensorFlow, or PyTorch, you will notice the meticulous attention given to their docstrings. These annotations help clarify the inner workings of various functions and classes, establishing a standard we should aspire to emulate in our code.
Remember, when you craft a docstring, you are narrating a story. You are elucidating the hows and whys of your code, guiding the reader through the complexities and nuances of your thought process. This is especially crucial in data science and AI, where mathematical and statistical complexities can obscure the underlying logic.
Additionally, writing docstrings is a valuable exercise for emerging data scientists or AI developers. It compels you to engage deeply with your code, ensuring that you understand it well enough to explain it simply. This practice also prepares you for collaborative efforts, where your code and its documentation will serve as a means of communication with your peers.
Finally, consider that your docstrings can also function as an educational resource for others within the Python and data science communities. Well-crafted docstrings in open-source projects often provide a valuable entry point for newcomers to learn and grasp how real-world data science operates. Thus, effective docstrings contribute to fostering a culture of learning and collaboration.
In closing, as we endeavor to leverage the capabilities of Python in data science, machine learning, and AI, let’s not overlook the significance of conveying our code's intent and functionality. Let’s commit to including clear and informative docstrings that guide, elucidate, and educate. The Zen of Python reminds us that “Readability counts,” and docstrings are essential allies in achieving this goal. As we write our code, let’s also invest in our docstrings; for today’s challenges can pave the way for tomorrow’s insights.
Thank You for Reading
Are you interested in further exploring career opportunities in data science? I offer personalized career coaching and maintain a weekly email list aimed at assisting job seekers in the data profession. Feel free to reach out for more information.
Thank you for your time! I welcome your thoughts and ideas. Whether you want to say hello or share feedback, I look forward to connecting with you soon. You can find me on Twitter: @adamrossnelson or LinkedIn: Adam Ross Nelson.