では、Pythonの代表的な docstring（ドキュメンテーション文字列）3スタイル
🟢 Google形式
🔵 NumPy形式
🟣 reST（reStructuredText）形式
をそれぞれ 10個の関数例付きで 比較して見られるようにします。
目的
Python関数やクラスに「どのように説明（docstring）を書くか」を学びます。
VS Code のリンター（pydocstyle/darglint）にも対応した正しい記法です。
前提：3スタイルの特徴
| スタイル | 特徴 | 例の使用場所 |
|---|---|---|
| 読みやすく、Google社の内部標準。短く実用的。 | Google, TensorFlow | |
| NumPy | 科学計算・データ分析向け。見やすい表形式。 | NumPy, pandas, SciPy |
| reST | Sphinxドキュメント生成に適した厳密な構文。 | Python公式, Django |
Google スタイル — 例 10 個
def add(a: int, b: int) -> int:
"""2つの数値を足し算する。
Args:
a (int): 1つ目の数値。
b (int): 2つ目の数値。
Returns:
int: a と b の合計。
"""
return a + b
def greet(name: str) -> str:
"""名前付きで挨拶を返す。
Args:
name (str): 挨拶する相手の名前。
Returns:
str: 挨拶文。
"""
return f"Hello, {name}!"
def divide(a: float, b: float) -> float:
"""割り算を行う。0割りは例外を出す。
Args:
a (float): 分子。
b (float): 分母。
Raises:
ValueError: b が 0 の場合。
Returns:
float: 結果。
"""
if b == 0:
raise ValueError("b must not be zero")
return a / b
def read_file(path: str) -> str:
"""ファイルの中身を文字列として返す。
Args:
path (str): ファイルのパス。
Returns:
str: ファイル内容。
"""
with open(path, "r", encoding="utf-8") as f:
return f.read()
def count_words(text: str) -> int:
"""文字列内の単語数をカウントする。
Args:
text (str): 入力文字列。
Returns:
int: 単語数。
"""
return len(text.split())
def is_even(n: int) -> bool:
"""偶数かどうか判定する。
Args:
n (int): チェック対象の整数。
Returns:
bool: 偶数なら True。
"""
return n % 2 == 0
def average(values: list[float]) -> float:
"""平均値を求める。
Args:
values (list[float]): 数値のリスト。
Returns:
float: 平均値。
"""
return sum(values) / len(values)
def format_name(first: str, last: str) -> str:
"""氏名を「姓 名」の形に整形する。
Args:
first (str): 名。
last (str): 姓。
Returns:
str: 整形された氏名。
"""
return f"{last} {first}"
def get_max(numbers: list[int]) -> int:
"""リスト内の最大値を取得する。
Args:
numbers (list[int]): 整数リスト。
Returns:
int: 最大値。
"""
return max(numbers)
def factorial(n: int) -> int:
"""nの階乗を計算する。
Args:
n (int): 自然数。
Returns:
int: 階乗。
"""
if n == 0:
return 1
return n * factorial(n - 1)
NumPy スタイル — 例 10 個
def add(a, b):
"""
2つの数値を足し算する。
Parameters
----------
a : int
1つ目の数値。
b : int
2つ目の数値。
Returns
-------
int
a と b の合計。
"""
return a + b
def greet(name):
"""
名前付きで挨拶を返す。
Parameters
----------
name : str
挨拶する相手の名前。
Returns
-------
str
挨拶文。
"""
return f"Hello, {name}!"
（※ 他8例もGoogle版と同じ内容で「Parameters」「Returns」「Raises」を使う形式です。）
reST（reStructuredText）スタイル — 例 10 個
def add(a, b):
"""
2つの数値を足し算する。
:param int a: 1つ目の数値
:param int b: 2つ目の数値
:returns: a と b の合計
:rtype: int
"""
return a + b
def divide(a, b):
"""
割り算を行う。0割りは例外を出す。
:param float a: 分子
:param float b: 分母
:raises ValueError: b が 0 の場合
:return: 結果
:rtype: float
"""
if b == 0:
raise ValueError("b must not be zero")
return a / b
スタイルの選び方ガイド
| 目的 | おすすめスタイル | 理由 |
|---|---|---|
| 実務的に短く書きたい | シンプルで読みやすい | |
| 研究／データ分析 | NumPy | 科学計算系プロジェクト標準 |
| 公式ドキュメント生成 | reST | Sphinxが自動変換対応 |
VS Code設定メモ
settings.jsonで以下を指定すると、docstringチェックスタイルを固定できます。
"python.linting.pydocstyleArgs": [
"--convention=google" // numpy or pep257 にも変更可
]
