Pythonのコメントの書き方とDocstring徹底解説｜可読性・保守性を高めるベストプラクティス

# 入力がNoneのときは既定のタイムアウトを使う（外部APIが閾値を要求するため）
def compute_timeout(user_timeout: int | None, default: int = 5) -> int:
    if user_timeout is None:
        return default
    return max(0, user_timeout)

threshold = 0.8  # ROC-AUCの実験結果に基づく暫定値
total = price * qty  # 税抜合計

total = price * qty  # 価格に数量を掛ける ← これはコードを繰り返しているだけ

def fetch_user(user_id: str) -> dict:
    # ユーザー情報の取得方針
    # - まずローカルキャッシュを参照（TTL=60秒）
    # - キャッシュにない場合はHTTPでフェッチ
    # - 404はNoneを返さず例外を送出して上位で扱う（呼び出し側でログ集約）
    ...

# TODO: v2でページング対応を実装する（API側の対応が完了してから）
# FIXME: タイムゾーンの扱いが不正確（夏時間切替で1時間ずれる）
# HACK: 互換性維持のため空文字をNoneに変換している

# old_validate(user)  # 古い検証は停止
new_validate(user)

def validate(user, *, use_new: bool = True) -> None:
    if use_new:
        new_validate(user)
    else:
        legacy_validate(user)

# なぜ: BigQueryは1クエリあたりの結果行数に上限があるため、日次で分割して取得する
def fetch_daily_partitioned(...):
    ...

from collections.abc import Iterable

def topk(items: Iterable[int], k: int) -> list[int]:
    """上位k件を降順で返します。重複は保持します。"""
    ...

# ここでユーザーがアクティブかつ課金中で...（長い説明）
if user.is_active and user.plan.is_paid and not user.is_suspended:
    ...

def is_billable(user: User) -> bool:
    return user.is_active and user.plan.is_paid and not user.is_suspended

if is_billable(user):
    ...

# pyproject.toml
[tool.ruff]
line-length = 88
select = ["E", "F", "W", "D"]  # pydocstyleルールを含める
ignore = ["D104"]              # パッケージの__init__にDocstring不要など

[tool.ruff.pydocstyle]
convention = "google"          # または "numpy", "pep257"

[tool.black]
line-length = 88

"""データ処理ユーティリティ群。

このモジュールは入出力と前処理を提供します。
"""

def normalize(text: str) -> str:
    """前後空白を削除し小文字化します。"""
    return text.strip().lower()

def slugify(text: str) -> str:
    """URLセーフなスラッグに変換する。"""

def connect_dsn(dsn: str, timeout: float = 3.0) -> "Connection":
    """DSNから接続を確立する。

    接続が確立できない場合はTimeoutErrorを送出します。
    再試行は行いません。
    """

class Cache:
    """LRU方式のメモリキャッシュ。

    スレッドセーフではありません。プロセス内での軽量用途に限ります。
    """

    def __init__(self, capacity: int = 128) -> None:
        """キャッシュ容量を指定します。

        capacity: 最大エントリ数。0以下はValueError。
        """

def moving_average(xs: list[float], window: int) -> list[float]:
    """移動平均を計算します。

    Args:
        xs: 元データの数列。
        window: 窓幅。1以上である必要があります。

    Returns:
        各位置の移動平均値のリスト。長さはlen(xs) - window + 1。

    Raises:
        ValueError: windowが1未満、またはwindowがlen(xs)を超える場合。

    Examples:
        >>> moving_average([1, 2, 3, 4], 2)
        [1.5, 2.5, 3.5]
    """
    if window < 1 or window > len(xs):
        raise ValueError("invalid window")
    return [
        sum(xs[i : i + window]) / window
        for i in range(len(xs) - window + 1)
    ]

def zscore(x):
    """標準化した配列を返す。

    Parameters
    ----------
    x : array_like
        標本データ。

    Returns
    -------
    z : ndarray
        平均0、分散1に正規化されたデータ。

    Examples
    --------
    >>> import numpy as np
    >>> zscore(np.array([1, 2, 3])).round(3)
    array([-1.225,  0.   ,  1.225])
    """
    import numpy as np
    x = np.asarray(x, dtype=float)
    return (x - x.mean()) / x.std(ddof=0)

def read(path: str, encoding: str = "utf-8") -> str:
    """ファイルを読み込みます。

    :param str path: ファイルパス。
    :param str encoding: 文字エンコーディング。
    :returns: ファイル内容。
    :rtype: str
    :raises FileNotFoundError: ファイルが存在しない場合。
    """
    with open(path, "r", encoding=encoding) as fp:
        return fp.read()

from collections.abc import Sequence

def percentile(xs: Sequence[float], p: float) -> float:
    """百分位数を返します。

    0 <= p <= 100。xsが空ならValueError。

    Raises:
        ValueError: xsが空、またはpが範囲外。
    """
    if not xs or not (0 <= p <= 100):
        raise ValueError("invalid arguments")
    ...

# docs/conf.py
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",      # Google/NumPyスタイルをreSTに変換
    "sphinx.ext.intersphinx",
    "sphinx_autodoc_typehints", # 型ヒントをDocstringに反映
]
intersphinx_mapping = {"python": ("https://docs.python.org/3", {})}
autodoc_typehints = "description"  # 引数説明に型を表示

pdoc -o docs html your_package

# ルールチェック
ruff check .

# 自動修正可能なものは修正
ruff check . --fix

# file: textutil.py
def normalize(name: str) -> str:
    """前後空白を削除し小文字にします。

    Examples:
        >>> normalize(" Foo  ")
        'foo'
    """
    return name.strip().lower()


if __name__ == "__main__":
    import doctest

    # doctestを実行して結果を表示
    failures, tests = doctest.testmod(optionflags=doctest.ELLIPSIS)
    print(f"{tests} tests, {failures} failures")

    # 動作確認の通常出力
    print(normalize(" Bar  "))

count = len(items)  # itemsの長さを数える ← 反復
# 2021-01-01: この機能は使われていない（実際は使われている）

# 外部仕様: 空入力は0件として扱う（API契約より）
count = len(items)

def load(path: str, *, cache: bool = True) -> str:
    """ファイルを読み込みます。"""  # cacheの説明がない

def load(path: str, *, cache: bool = True) -> str:
    """ファイルを読み込みます。

    Args:
        path: ファイルパス。
        cache: キャッシュを利用するか。デフォルトTrue。
    """

def dedup_sorted(xs: list[int]) -> list[int]:
    """ソート済み配列の重複を削除して返す。

    前提: xsは昇順ソート済み。O(n)で走査し、安定性は考慮しない。
    破壊的変更は行わない（新しいリストを返す）。
    """
    ...