Docstring Formats in Python 2026
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
Why the Docstring Format Matters
A docstring is the first string literal in a function, class or module. Python stores it in the __doc__ attribute, help() prints it, and editors show it as a tooltip when you call the function. A consistent format turns this text into reliable documentation that tools can read.
The three common formats are Google style, NumPy style and reStructuredText. Google style is compact and easy to read in code. NumPy style uses underlined section headers and suits scientific functions with many parameters. reStructuredText uses :param: fields and is the traditional Sphinx format. Sphinx can read Google and NumPy styles too, through its napoleon extension.
The best format is the one your whole project uses. Mixing styles makes generated documentation look uneven and makes it harder for readers to find the parameter they need.
Type hints and docstrings work together. Hints state the types in a form that tools can check, while the docstring explains meaning, units, valid ranges and the errors a caller should expect.
Worked Example: A Google-Style Docstring You Can Inspect
We document a small function and read its docstring back through the standard library.
import inspect
def moving_average(values: list[float], window: int = 3) -> list[float]:
"""Return the simple moving average of a list.
Args:
values: Numbers in time order.
window: Number of points per average. Must be at least 1.
Returns:
A list with len(values) - window + 1 averages.
Raises:
ValueError: If window is smaller than 1.
"""
if window < 1:
raise ValueError("window must be at least 1")
return [sum(values[i:i + window]) / window for i in range(len(values) - window + 1)]
print(moving_average([1, 2, 3, 4, 5]))
print(inspect.getdoc(moving_average).splitlines()[0])The function returns [2.0, 3.0, 4.0], and inspect.getdoc returns the cleaned docstring, whose first line is the one-sentence summary. That summary line is what most tools show in lists and tooltips, so it should stand on its own.
Practical Tips
Write the summary line in the imperative mood, such as "Return the moving average", and keep it under one line. Add details in the following paragraphs.
Run python -m pydoc on your module to see the documentation as users will see it.
Common Mistakes
- Repeating the type hints in the docstring and letting the two drift apart.
- Writing a summary line that only repeats the function name.
- Documenting parameters that no longer exist after a refactor.
- Mixing Google and NumPy styles in one project.
Quick Summary
- Docstrings live in __doc__ and appear in help().
- Google, NumPy and reST are the common formats.
- Pick one format for the whole project.
- Explain meaning and errors, not only types.
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