Docstring-Driven Development (DDD) is a practice where the primary artifact of a component — a function, class, or module — is its docstring, which serves as both documentation and executable specification. It matters when teams need to align on behavior across code, tests, and onboarding, especially in polyglot environments, evolving APIs, and collaborative systems where shared understanding is fragile.
Writing the First Docstring
The docstring is not a comment. It is the single source of truth for how a unit of code behaves. It must be written before any implementation, and its structure defines the contract.
A minimal docstring begins with a concise summary line, followed by a blank line, then a detailed description. This description is structured in natural language using a standard layout:
def process_user_data(raw_data: dict) -> dict:
"""Transform raw user data into a canonical format.
This function normalizes user information from various sources into a consistent
schema. It handles missing fields, standardizes names, and enriches data with
derived values.
The input is a flat dictionary with keys like:
- user_id
- first_name
- last_name
- email_address
- created_at
- preferences_json
Output keys include:
- id
- name
- email
- created_at
- preferences
- full_name
- is_active
- age_group
For example:
{
"user_id": 42,
"first_name": "Alicia",
"last_name": "Chen",
"email_address": "[email protected]",
"created_at": "2023-01-15T10:30:00Z",
"preferences_json": '{"theme": "dark", "notifications": true}'
}
Output:
{
"id": 42,
"name": "Alicia Chen",
"email": "[email protected]",
"created_at": "2023-01-15T10:30:00Z",
"preferences": {"theme": "dark", "notifications": true},
"full_name": "Alicia Chen",
"is_active": true,
"age_group": "adult"
}
"""
# Implementation followsThe structure is self-explanatory and can be consumed by developers, testers, and product managers. It is not just documentation — it is a specification. The docstring defines the shape of input and output, and includes a real example of both.
Using the Docstring as a Test Specification
The docstring is not just read — it is executed. Tools extract examples from the docstring and run them as automated tests.
A standard tool like pytest with pytest-docstring or doctest can parse the example blocks and validate the function against them.
When the process_user_data function is run in a test suite, the following happens:
- The input dictionary is passed to the function.
- The output is compared to the expected output with exact key-value matching.
- The test fails with a clear message if any field differs:
Failed example:
process_user_data({
"user_id": 42,
"first_name": "Alicia",
"last_name": "Chen",
"email_address": "[email protected]",
"created_at": "2023-01-15T10:30:00Z",
"preferences_json": '{"theme": "dark", "notifications": true}'
})
Expected:
{
"id": 42,
"name": "Alicia Chen",
"email": "[email protected]",
"created_at": "2023-01-15T10:30:00Z",
"preferences": {"theme": "dark", "notifications": true},
"full_name": "Alicia Chen",
"is_active": true,
"age_group": "adult"
}
Got:
{
"id": 42,
"name": "Alicia Chen",
"email": "[email protected]",
"created_at": "2023-01-15T10:30:00Z",
"preferences": {"theme": "dark", "notifications": true},
"full_name": "Alicia Chen",
"is_active": true,
"age_group": "young"
}The error reveals that the age_group field was incorrect — it returned young instead of adult. This failure is immediate and precise.
Deriving Implementation from the Docstring
The docstring drives the implementation. Developers write code to match the specification, guided by the example.
The function body is not an afterthought — it is a direct response to the docstring. As the implementation evolves, the docstring is updated, and tests are automatically re-run.
When a new requirement is added — for instance, that is_active should be true if created_at is within the last 30 days — the docstring is updated:
For example:
{
"user_id": 42,
"first_name": "Alicia",
"last_name": "Chen",
"email_address": "[email protected]",
"created_at": "2023-01-15T10:30:00Z",
"preferences_json": '{"theme": "dark", "notifications": true}'
}
Output:
{
"id": 42,
"name": "Alicia Chen",
"email": "[email protected]",
"created_at": "2023-01-15T10:30:00Z",
"preferences": {"theme": "dark", "notifications": true},
"full_name": "Alicia Chen",
"is_active": true,
"age_group": "adult"
}
Note: Users created within the last 30 days are marked as active.This note is not a comment — it is a rule. The implementation must now include logic to compute is_active based on the date.
The test suite fails because is_active is always true regardless of created_at. The developer adds a check:
from datetime import datetime, timedelta
def process_user_data(raw_data: dict) -> dict:
# ... existing code ...
now = datetime.now()
created_at = datetime.fromisoformat(raw_data["created_at"].replace("Z", "+00:00"))
thirty_days_ago = now - timedelta(days=30)
is_active = created_at > thirty_days_ago
output["is_active"] = is_activeThe test passes. The docstring is now both specification and test.
Extracting Configuration and Contracts from Docstrings
Docstrings grow to include additional metadata. They become a contract for the interface.
A more complex function may include type hints and structured examples:
def build_order_report(
orders: list[dict],
include_summary: bool = True,
format: str = "json"
) -> str:
"""Generate a formatted report of orders.
Args:
orders: List of order dictionaries. Each order must have:
- order_id
- customer_id
- total
- status
- items (list of dicts with name, quantity, price)
include_summary: Whether to include a summary at the top.
format: Output format. One of: "json", "xml", "text".
Returns:
A string report in the specified format.
Raises:
ValueError: If orders is empty.
Examples:
>>> build_order_report(
... orders=[{
... "order_id": 1001,
... "customer_id": 5001,
... "total": 129.95,
... "status": "shipped",
... "items": [
... {"name": "Laptop", "quantity": 1, "price": 999.99},
... {"name": "Mouse", "quantity": 2, "price": 29.99}
... ]
... }],
... include_summary=True,
... format="json"
... )
'{"summary": {"total_orders": 1, "total_value": 129.95}, "orders": [...]}'
>>> build_order_report(
... orders=[],
... include_summary=False,
... format="xml"
... )
Traceback (most recent call last):
...
ValueError: Orders list is empty.
"""
# ImplementationThe docstring now serves as a full API contract. It includes:
- Required and optional parameters with type and description.
- Return value structure.
- Exception conditions.
- Multiple, realistic usage examples.
Tools can generate API documentation from this docstring alone, using sphinx, mkdocs, or pydoc.
Automating the Docstring Lifecycle
A docstring-driven workflow includes automation to ensure the docstring is always correct.
A Makefile script runs all docstring-based tests and validates the contract:
test:
pytest tests/ --doctest-modules --doctest-glob="*.py"
check-docstrings:
pytest tests/ --doctest-modules --doctest-continue-on-failure
lint:
black .
isort .
flake8 .
ci: lint test check-docstringsThe CI pipeline runs make ci on every push. If a docstring example fails, the pipeline fails with a clear error.
When a developer pushes a change that breaks the build_order_report example, the CI output shows:
============================= test session starts ==============================
collected 3 items
tests/test_reports.py::test_build_order_report[json] PASSED
tests/test_reports.py::test_build_order_report[xml] FAILED
tests/test_reports.py::test_build_order_report[empty] FAILED
=================================== FAILURES ===================================
_________________________ test_build_order_report[xml] _________________________
>>> build_order_report(
... orders=[{
... "order_id": 1001,
... "customer_id": 5001,
... "total": 129.95,
... "status": "shipped",
... "items": [
... {"name": "Laptop", "quantity": 1, "price": 999.99},
... {"name": "Mouse", "quantity": 2, "price": 29.99}
... ]
... }],
... include_summary=True,
... format="xml"
... )
Expected:
'<report><summary><total_orders>1</total_orders><total_value>129.95</total_value></summary><orders><order><order_id>1001</order_id>...</orders></report>'
Got:
'<report><summary><total_orders>1</total_orders><total_value>129.95</total_value><status>shipped</status></summary><orders><order><order_id>1001</order_id>...</orders></report>'The test fails because the status field is included in the summary — but it was not expected. The docstring example is out of sync with the actual output.
Common Pitfalls and Sharp Edges
1. Assumed types not in the docstring
A function expects datetime objects in created_at, but the example uses strings. The test passes, but in production, the created_at field is a datetime object. The docstring must explicitly state the expected format.
2. Field order in nested structures
The docstring expects {"theme": "dark", "notifications": true}, but the actual output is {"notifications": true, "theme": "dark"}. The test fails because dictionaries are unordered. The solution is to use json.dumps(..., sort_keys=True) or to explicitly describe the expected order.
3. Default values not tested
The format argument defaults to "json", but no example uses the default. The test suite misses the case where format="json" is not explicitly passed. The docstring should include a minimal example with default values.
4. Ambiguous examples
An example uses total: 129.95, but the function expects total: 129.950000. The test fails due to floating-point precision. The solution is to use math.isclose or to format the expected value to a specific number of decimal places.
5. Type mismatches in examples
The docstring uses a list of dict, but one example passes a tuple of dict. The test fails because isinstance(items, list) returns False. The docstring must clarify that input is a list, not just an iterable.
6. Uncaught exceptions
The docstring says Raises: ValueError, but the function raises TypeError for invalid orders. The test suite must include assertRaises for ValueError but not for TypeError.
7. Example updates require docstring review
When a function is refactored, the examples may become outdated. The docstring is no longer a true specification. A review step in the PR checklist ensures that all examples are updated and pass.
Adapting Docstring-Driven Dev to Other Languages
The pattern is not limited to Python. In JavaScript, a docstring-driven function uses JSDoc:
/**
* Transforms raw user data into a canonical format.
*
* @param {Object} raw_data - Raw user information.
* @param {number} raw_data.user_id - Unique identifier.
* @param {string} raw_data.first_name - First name.
* @param {string} raw_data.last_name - Last name.
* @param {string} raw_data.email_address - Email address.
* @param {string} raw_data.created_at - ISO 8601 timestamp.
* @param {string} raw_data.preferences_json - JSON string.
* @returns {Object} Normalized user object.
* @property {number} id - Same as user_id.
* @property {string} name - Concatenation of first and last name.
* @property {string} email - Same as email_address.
* @property {string} created_at - ISO 8601 timestamp.
* @property {Object} preferences - Parsed JSON from preferences_json.
* @property {string} full_name - Same as name.
* @property {boolean} is_active - True if created within 30 days.
* @property {string} age_group - 'young', 'adult', or 'senior'.
*
* @example
* const input = {
* user_id: 42,
* first_name: 'Alicia',
* last_name: 'Chen',
* email_address: '[email protected]',
* created_at: '2023-01-15T10:30:00Z',
* preferences_json: '{"theme": "dark", "notifications": true}'
* };
*
* const output = processUserData(input);
* // {
* // id: 42,
* // name: 'Alicia Chen',
* // email: '[email protected]',
* // created_at: '2023-01-15T10:30:00Z',
* // preferences: { theme: 'dark', notifications: true },
* // full_name: 'Alicia Chen',
* // is_active: true,
* // age_group: 'adult'
* // }
*
* @throws {Error} If raw_data is missing required fields.
*/
function processUserData(raw_data) {
// Implementation
}The same principles apply: the docstring is both documentation and test specification. Tools like Jest or Mocha can extract examples and run them as tests.
Summary
Docstring-Driven Development is not a documentation tool. It is a development practice where the docstring is the heart of the component. It drives implementation, validates behavior, and serves as a contract across teams. It fails silently when examples are outdated, when types are assumed but not specified, or when the output does not match the expected structure. It succeeds when every function is self-documenting, self-testing, and self-validating — and when a change to the docstring is a change to the system.
This page was rewritten on 11 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.
Join the Newsletter
Get the latest updates and deep insights shipped directly to your inbox.