Docstring Formats in Python 2026 – Best Practices for Writing Functions
Well-written docstrings are essential for maintainable, readable, and self-documenting Python code. In 2026, choosing the right docstring format and following consistent conventions significantly improves developer experience and tool support.
TL;DR — Recommended Formats 2026
- Google Style — Most popular and readable
- NumPy/SciPy Style — Excellent for scientific and data-heavy functions
- reStructuredText (reST) — Traditional, used by Sphinx
- Use consistent style across your entire project
1. Google Style Docstring (Recommended)
def calculate_win_rate(
wins: int,
total_games: int,
include_ties: bool = False
) -> float:
"""Calculate win rate as a percentage.
Args:
wins (int): Number of wins.
total_games (int): Total number of games played.
include_ties (bool, optional): Whether to count ties as half wins.
Defaults to False.
Returns:
float: Win percentage (0.0 to 100.0).
Raises:
ValueError: If total_games is zero or negative.
"""
if total_games <= 0:
raise ValueError("total_games must be positive")
if include_ties:
effective_wins = wins + 0.5 * (total_games - wins)
return (effective_wins / total_games) * 100
return (wins / total_games) * 100
2. NumPy Style Docstring
def process_user_data(
user_ids: list[int],
include_inactive: bool = False
) -> dict:
"""
Process user data and return statistics.
Parameters
----------
user_ids : list of int
List of user IDs to process.
include_inactive : bool, optional
Whether to include inactive users. Default is False.
Returns
-------
dict
Dictionary containing user statistics.
Examples
--------
>>> process_user_data([1, 2, 3])
{'total_users': 3, 'active_users': 2}
"""
# implementation...
pass
3. Best Practices for Docstrings in 2026
- Choose **one style** and use it consistently across the project
- Include Args, Returns, Raises, and Examples sections
- Use type hints in the function signature (not just in docstring)
- Keep docstrings concise but informative
- Use Google Style for most general projects
- Use NumPy Style for data science / scientific computing projects
Conclusion
Good docstrings improve code readability, IDE support, and documentation generation. In 2026, consistent use of Google or NumPy style docstrings is considered a professional standard when writing functions.
Next steps:
- Adopt one docstring style across your entire codebase
- Related articles: Writing Functions in Python 2026 • Efficient Python Code 2026