概要（docstring は「使い方」をコードの中に残す公式な説明書）
ドキュメンテーション文字列（docstring）は、関数・メソッド・クラス・モジュールの定義直後に書く、三重引用符で囲まれた説明文です。役割は「このオブジェクトは何をするのか」「どう使うのか」を、コードのそばに正しく残すこと。コメントが「実装の理由」を補足するのに対し、docstring は「外からの使い方」を案内します。help() や IDE のヒントで表示され、未来の自分やチームの仲間の生産性を大きく上げます。
def add(a, b):
"""2つの数値を足し算して返す。"""
return a + b
基本構文と書く位置（ここが重要）
三重引用符で定義直後に書く
docstring は定義の“次の行”に、””” … “”” または ”’ … ”’ の形で書きます。単一行でも複数行でも構いませんが、最初の1行は短い要約にします。その後に空行を挟んで、詳細や引数・返り値、例外、使用例などを続けると読みやすくなります。
def power(x, exp=2):
"""x を exp 乗して返す。
引数:
x: 基数
exp: べき指数（既定値 2）
返り値:
計算結果の数値
"""
return x ** exp
help() と doc で参照しやすくなる
docstring は実行時にも取り出せます。help(関数) で整形された説明が表示され、関数.doc で生の文字列を取得できます。これにより、REPLやテスト、ドキュメント生成ツールから容易に活用できます。
print(power.__doc__)
help(power)
実務で役立つ書き方（要約→詳細→仕様を明確に）
要約の1行で「何をするか」を即伝える
最初の1文は、専門用語を最小限にして簡潔に。読む人が1秒で用件を掴めることを目指します。文末は句点で締めると整います。
def normalize(name: str) -> str:
"""名前の前後空白を除去し、小文字化して返す。"""
return name.strip().casefold()
詳細は「入力・出力・副作用・例外」を丁寧に
引数と返り値の意味と型、前提条件、発生しうる例外、副作用（ファイル書き込みなど）があれば明示します。使用例を1つ載せると理解が早まります。
def divide(a: float, b: float) -> float:
"""a を b で割って返す。
引数:
a: 被除数
b: 除数（0 は不可）
返り値:
a / b の計算結果
例外:
ZeroDivisionError: b が 0 の場合
使用例:
>>> divide(6, 3)
2.0
"""
return a / b
複数行は「空行とインデント」で読みやすく整える
複数行 docstring は、要約→空行→詳細の順に。箇条書きにする代わりに、短い文を段落として分けると、整形や閲覧時に崩れません。
関数・クラス・モジュールの docstring 例
関数の docstring（処理の目的と入出力）
関数では「何をする」「入力は何」「何を返す」を基本セットで書きます。オプション引数の既定値が意味を持つ場合は、その意図も言語化します。
def format_price(amount: int, currency: str = "JPY", with_tax: bool = False) -> str:
"""金額を通貨コード付き文字列に整形する。
with_tax=True の場合は簡易的に 10% を加算し丸める。
"""
total = round(amount * (1.1 if with_tax else 1))
return f"{currency} {total}"
クラスとメソッドの docstring（振る舞いと契約）
クラスの docstring では「何のための型か」を説明し、主要メソッドは引数・返り値・例外・副作用を明確にします。クラスの状態に依存する前提も書いておくとトラブルが減ります。
class Counter:
"""インクリメント専用の簡易カウンタ。"""
def __init__(self, start: int = 0):
"""初期値 start でカウントを開始する。"""
self.n = start
def inc(self) -> int:
"""カウントを 1 増やし、現在値を返す。"""
self.n += 1
return self.n
モジュールの docstring（ファイル全体の目的）
モジュール先頭の docstring には「このファイルは何を提供するか」を書きます。使用例や注意事項を短く添えると、初見の読者が迷いません。
"""テキスト整形ユーティリティ。
strip/lower/casefold を組み合わせた関数群を提供する。
"""
注意点の深掘り（ズレ・形式・保守性）
実装と docstring の「ズレ」は最悪の敵
仕様変更をしたら、docstring を必ず更新します。嘘の説明は、エラーよりも厄介です。テストに「docstring に書いた使用例（doctest）」を取り入れると、説明と実装の一貫性を機械的に検証できます。
def add(a, b):
"""2つの数値を加算する。
使用例:
>>> add(2, 3)
5
"""
return a + b
コメントとの役割分担を守る
コメントは「なぜその実装にしたか」の補足、docstring は「どう使うか」の説明。目的が異なるため、両者を混同しないほどコードが綺麗になります。
国際化と文字コードの配慮
日本語の docstring は読みやすい一方、公開ライブラリや海外チームでは英語が無難です。プロジェクト方針に合わせて言語を統一すると、サポートとレビューが楽になります。
例題で身につける（定番から一歩先まで）
使用例付きの関数 docstring（最小セット）
def slugify(text: str) -> str:
"""見出し文字列をURL用スラッグに変換する。
前後空白を除去し、小文字化して、空白をハイフンに置換する。
使用例:
>>> slugify(" Coffee Latte ")
'coffee-latte'
"""
s = text.strip().casefold()
return "-".join(s.split())
例外・前提条件を明記した API
def read_json(path: str) -> dict:
"""ファイルパスから JSON を読み取り dict を返す。
前提:
path は既存ファイルであること。
例外:
FileNotFoundError: ファイルが存在しない場合
JSONDecodeError: JSON が不正な場合
"""
import json
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
クラスの使用例を含んだ docstring
class Stopwatch:
"""簡易ストップウォッチ。
使用例:
>>> sw = Stopwatch()
>>> sw.start(); sw.stop() # 単純な測定
"""
def start(self) -> None:
"""計測を開始する。"""
...
def stop(self) -> float:
"""計測を停止し、経過秒数を返す。"""
...
まとめ
docstring は「使い方の説明書」をコードのそばに置くための公式な仕組みです。定義直後に三重引用符で書き、最初の1行で要約、次に詳細と仕様（引数・返り値・例外・副作用・使用例）を丁寧に。help() で即参照でき、IDE や自動ドキュメント生成にも活用されます。嘘の説明は最大のバグ源なので、変更時は必ず更新し、必要なら doctest の例で説明と実装の一致を検証しましょう。短く、正確に、親切に——それがプロの docstring です。