Every analysis function you've written so far has a name but no documentation. When your co-author opens the script and sees make_table_row, what tells her what it expects and what it returns?
format_stat_line from Day 5 builds the statistics line. But I just named the function — nothing explains the parameters or what the rank integer is for.
A docstring. The first statement inside a function, wrapped in triple quotes, describes what the function does, what each parameter means, and what it returns. Python stores it as __doc__ and documentation tools surface it automatically:
def make_table_row(group: str, stats: dict, rank: int) -> str:
"""Return a formatted table row for the methods section.
Args:
group: treatment group name (normalised).
stats: dict with keys 'n', 'mean_outcome', 'mean_age'.
rank: 1-based rank by mean outcome (highest = rank 1).
Returns:
Formatted string like '#1 Control — N: 87 | Mean Outcome: 4.72 | Mean Age: 34.2'
"""
Does the docstring change how the function runs? Or is it just a comment?
Just documentation — no effect on execution. But help(make_table_row) in a Python REPL shows it, and every IDE displays it as a tooltip. Your co-author doesn't need to read the function body to understand the contract.
So the docstring is the methods section entry for the function — write it once, it's there for every rerun request.
A specification you can cite. Exactly what a function is:
def make_table_row(group: str, stats: dict, rank: int) -> str:
"""Return a formatted ranked table row for the methods section."""
line = f"#{rank} {group.title()} — N: {stats['n']:,} | Mean Outcome: {stats['mean_outcome']:.2f} | Mean Age: {stats['mean_age']:.1f}"
print(f"Table row: {line}")
return line
format_stat_line was useful. make_table_row is publishable.
Type hints — group: str, stats: dict, rank: int — are documentation too. They don't enforce types at runtime, but they signal to every reader what the expected inputs are. Combine type hints with docstrings and the function is self-explaining.
A Python function is a named, reusable specification.
def function_name(param: type) -> return_type:
"""One-line summary. Extended description if needed."""
# body
return valueArgs: section: one line per parameter — name, type, meaningReturns: section: what is returned and in what shapeType hints (param: str, -> dict) are read by IDEs and type checkers. They don't raise errors at runtime for wrong types — they document the contract.
help() and __doc__help(make_table_row) prints the docstring in a REPL. make_table_row.__doc__ returns it as a string — useful for auto-generated documentation.
Every analysis function you've written so far has a name but no documentation. When your co-author opens the script and sees make_table_row, what tells her what it expects and what it returns?
format_stat_line from Day 5 builds the statistics line. But I just named the function — nothing explains the parameters or what the rank integer is for.
A docstring. The first statement inside a function, wrapped in triple quotes, describes what the function does, what each parameter means, and what it returns. Python stores it as __doc__ and documentation tools surface it automatically:
def make_table_row(group: str, stats: dict, rank: int) -> str:
"""Return a formatted table row for the methods section.
Args:
group: treatment group name (normalised).
stats: dict with keys 'n', 'mean_outcome', 'mean_age'.
rank: 1-based rank by mean outcome (highest = rank 1).
Returns:
Formatted string like '#1 Control — N: 87 | Mean Outcome: 4.72 | Mean Age: 34.2'
"""Does the docstring change how the function runs? Or is it just a comment?
Just documentation — no effect on execution. But help(make_table_row) in a Python REPL shows it, and every IDE displays it as a tooltip. Your co-author doesn't need to read the function body to understand the contract.
So the docstring is the methods section entry for the function — write it once, it's there for every rerun request.
A specification you can cite. Exactly what a function is:
def make_table_row(group: str, stats: dict, rank: int) -> str:
"""Return a formatted ranked table row for the methods section."""
line = f"#{rank} {group.title()} — N: {stats['n']:,} | Mean Outcome: {stats['mean_outcome']:.2f} | Mean Age: {stats['mean_age']:.1f}"
print(f"Table row: {line}")
return lineformat_stat_line was useful. make_table_row is publishable.
Type hints — group: str, stats: dict, rank: int — are documentation too. They don't enforce types at runtime, but they signal to every reader what the expected inputs are. Combine type hints with docstrings and the function is self-explaining.
A Python function is a named, reusable specification.
def function_name(param: type) -> return_type:
"""One-line summary. Extended description if needed."""
# body
return valueArgs: section: one line per parameter — name, type, meaningReturns: section: what is returned and in what shapeType hints (param: str, -> dict) are read by IDEs and type checkers. They don't raise errors at runtime for wrong types — they document the contract.
help() and __doc__help(make_table_row) prints the docstring in a REPL. make_table_row.__doc__ returns it as a string — useful for auto-generated documentation.
Anya is building a reproducible pipeline and needs a documented function that formats a ranked statistics row for the methods table. Write `make_table_row(group, stats, rank)` with a docstring, type hints, and an f-string that returns a string like `"#1 Control — N: 87 | Mean Outcome: 4.72 | Mean Age: 34.2"`.
Tap each step for scaffolded hints.
No blank-editor panic.