- 複数行コメント（ドキュメンテーションコメント）とコメントのベストプラクティス
- 1. docstring（ドキュメンテーション文字列）とは？
- 2. docstring と通常のコメント（#）の違い
- 3. docstring の基本ルール（推奨）
- 4. 代表的な docstring スタイル（例：Google / NumPy / reST）
- 5. docstring の実用例（モジュール／クラス／関数）
- 6. docstring に関するよくあるミス／注意点
- 7. コメント（#）のベストプラクティス
- 8. 自動チェック・ツール（知っておくと便利）
- 9. 実践例：良い docstring と コメントの比較
- 10. すぐ使えるチェックリスト
- 11. 練習
複数行コメント（ドキュメンテーションコメント）とコメントのベストプラクティス
ここでは docstring（ドキュメンテーション文字列） の正しい使い方、よくある間違い、代表的な書式（Google / NumPy / reST）と、現場で役立つ「コメントのベストプラクティス」を具体例つきでまとめます。初心者でもすぐ使えるチェックリスト付き。
1. docstring（ドキュメンテーション文字列）とは？
- Python の関数・クラス・モジュールの直後に置く 三重引用符（
"""..."""または'''...'''）で囲んだ文字列 のこと。 - 意味：そのオブジェクトの「説明書」。
help()や.__doc__から参照できます。 - 例：関数の説明、引数の意味、戻り値、例、例外などを記載。
def greet(name):
"""name に渡された人に挨拶する。"""
print(f"こんにちは、{name}さん")
help(greet) や greet.__doc__ で上の説明が表示されます。
2. docstring と通常のコメント（#）の違い
- docstring：外部に公開される説明（APIドキュメント）。ユーザーや他の開発者が
help()で見るためのもの。関数・クラス・モジュールの「先頭」に置く。 #コメント：実装者向けのメモ。行単位でコード内に置き、実行時は無視されます（docstringもプログラム実行時は基本影響なしだが、オブジェクトの属性として残る）。- 使い分け：
- 「この関数は何をするのか（仕様）」 → docstring
- 「このアルゴリズムでこうした理由（実装の裏話）」「TODO」「一時的に無効化」 →
#コメント
3. docstring の基本ルール（推奨）
- **1行目に短い要約（summary）**を書き、終わりにピリオドは不要（慣例）。
- 要約行の後に空行を入れ、必要なら詳細な説明を続ける。
- 引数・戻り値・例外・使用例を明確に。
- 英語/日本語はプロジェクトで統一。
- 型は書くと親切（型注釈があると重複するので状況によって使い分け）。
- docstring は APIの仕様 として信頼されるため、常に最新に保つ。
短いテンプレ：
短い要約行
（空行）
詳細な説明（必要なら複数行）。
Args:
arg1 (int): 説明
Returns:
bool: 説明
Raises:
ValueError: 説明
4. 代表的な docstring スタイル（例：Google / NumPy / reST）
Google スタイル（読みやすく、わりと簡潔）
def add(a, b):
"""2つの数を加算して返す。
Args:
a (int): 1つ目の数
b (int): 2つ目の数
Returns:
int: a と b の和
Examples:
>>> add(2, 3)
5
"""
return a + b
NumPy スタイル（科学計算のライブラリでよく使われる）
def add(a, b):
"""
2つの数を加算して返す。
Parameters
----------
a : int
1つ目の数
b : int
2つ目の数
Returns
-------
int
a と b の和
Examples
--------
>>> add(2, 3)
5
"""
return a + b
reStructuredText（Sphinxと相性が良い）
def add(a, b):
"""
2つの数を加算して返す。
:param a: 1つ目の数
:type a: int
:param b: 2つ目の数
:type b: int
:return: a と b の和
:rtype: int
"""
return a + b
どのスタイルを使うかはプロジェクトで統一しましょう（自動ドキュメント生成ツールとの相性で決めることが多い）。
5. docstring の実用例（モジュール／クラス／関数）
"""utility モジュール：簡単なユーティリティ関数を集めたもの."""
def divide(a, b):
"""a を b で割って結果を返す。
Args:
a (float): 分子
b (float): 分母
Returns:
float: 割り算の結果。 b が 0 のときは None を返す。
Raises:
TypeError: 引数が数値でない場合
"""
if not (isinstance(a, (int, float)) and isinstance(b, (int, float))):
raise TypeError("a と b は数値である必要があります")
if b == 0:
return None
return a / b
class Person:
"""人を表すクラス。
Attributes:
name (str): 名前
age (int): 年齢
"""
def __init__(self, name, age):
"""Person を初期化する。
"""
self.name = name
self.age = age
6. docstring に関するよくあるミス／注意点
- 単に長いコメントを
"""で囲んで関数内に置く（docstringの目的とずれる）→ docstring は「そのオブジェクトの説明」に限定する。 - コード変更で docstring を更新しない → ユーザを混乱させる（必ず一緒に直す習慣を）。
- 短すぎる要約行＋詳細がない →
help()しても役に立たない。 - docstring を大量に無意味に使う（小さな内部関数まで過剰に書くと保守コストが上がる）→ 公開APIや公共の関数に重点を。
7. コメント（#）のベストプラクティス
- 「なぜ（why）」を書く：どうやって（how）や何を（what）はコードで表現し、なぜその方法を選んだかを書きます。
例：# ここでバッファサイズを小さくするのはメモリ節約のため - 簡潔に：1〜2行でまとめる。長くなるなら別ドキュメントへ。
- コードの意図を説明：変数名や関数名では伝わらない「意図」を補足。
- TODO / FIXME の使い方：
# TODO: 修正理由（チケット番号）の形で残すと追跡しやすい。 - コメントを最新に保つ：コード変更時にコメントを更新するチェックを習慣化。
- コメントでロジックを正当化する：特殊ケースやワークアラウンドは必ず理由を書く。
- 過度なコメントは避ける：明らかに分かること（
i += 1 # iを1増やす）は不要。
8. 自動チェック・ツール（知っておくと便利）
（ツール名は参考として）
- pydocstyle：docstring ルールの自動チェック。
- flake8 / pylint：コメントやスタイル全般のチェック。
- Sphinx + autodoc：docstring から HTML ドキュメントを生成。
（導入する場合はプロジェクトに合わせたルールを決め、CI に組み込むと安心です。）
9. 実践例：良い docstring と コメントの比較
悪い（あまり助けにならない）：
def mult(x, y):
"""掛け算する。"""
# x と y を掛けるだけ
return x * y
良い（もう少し親切）：
def mult(x: int, y: int) -> int:
"""2つの整数を掛けて返す。
Args:
x (int): 乗算の左オペランド
y (int): 乗算の右オペランド
Returns:
int: x * y
Notes:
浮動小数点を使うケースでは型変換または別関数を使ってください。
"""
return x * y
コメントは実装の「理由」や注意点に使う：
# 注意: ここでキャッシュをクリアしないとメモリが増え続ける
cache.clear()
10. すぐ使えるチェックリスト
- 関数・クラス・モジュールには docstring があるか？（公開APIなら必須）
- docstring の最初の行は短い要約か？（約50文字以内推奨）
- 要約のあとに空行、必要なら詳細説明があるか？
- 引数（Args/Parameters）と戻り値（Returns）を書いているか？ 型は明記しているか？
- 例外（Raises）を明記しているか（例外を投げる場合）？
- 実装上の「なぜ」を
#コメントで補っているか？ - TODO や FIXME はチケット番号付きで管理されているか？
- コメントと docstring が最新の状態か？
11. 練習
- 小さな関数
factorial(n)を作って、Google スタイルの docstring を書いてみてください。 - 既存の関数を見つけて
help()を実行し、docstring の良し悪しを判断してみましょう。 - チームのコードで docstring スタイルを 1 つ決め、20行程度のコードに統一して適用してみる。