結論：
コメントは 「なぜそう書いたのか」を補足するもの、
Docstringは 「このコードの使い方を説明する公式な文書」 です。
目的が違うため、PEP 8では明確に使い分けるよう推奨されています。
コメントの基本ルール
- コードの内容そのものは書かない
→ 読めばわかることをコメントにするのはNG - 「なぜ」「意図」「背景」を書く
- 行頭に
#を置き、必要ならスペース1つ空ける
#ユーザーが未入力の場合はデフォルト名を使う
if not name:
name = "Guest"👉 悪い例：
# name が空なら Guest を代入 ← コードをそのまま書いているだけ
if not name:
name = "Guest"
コメントの種類
- 行コメント
- 行の前に置く
- 例：
# デバッグ用に一時的に出力 print(user)
- ブロックコメント
- 複数行に渡る説明をする
- 例：
# データベース接続の手順 # 1. 設定ファイルを読み込む # 2. 接続を確立する # 3. セッションを返す
Docstring とは？
- 関数・クラス・モジュールに付ける公式な説明文
- 文字列リテラル（
"""）で囲み、最初の行に概要を書く
def add(a: int, b: int) -> int:
"""
2つの整数を加算して返す関数。
Args:
a (int): 加算する1つ目の整数
b (int): 加算する2つ目の整数
Returns:
int: a と b の合計
"""
return a + b
👉 Docstringは help() や 自動ドキュメント生成ツール（Sphinxなど）で利用されます。
Docstring の書き方のポイント
- 1行目：短く概要を説明する（ピリオドで終える）
- 2行目以降：必要なら引数・戻り値・例外などを記載
- フォーマット：Google形式、NumPy形式、reST形式などがある
→ プロジェクト内で統一することが大切
よくある間違い
- コメントが「コードの説明」になっている
- Docstringがなく、関数の使い方が不明
- コメントやDocstringを更新せず、コードと不一致になる
実務でのポイント
- コメントは最小限、Docstringは丁寧に
- リファクタリング時に必ず更新
- 新規メンバーが読んでも理解できるか？ を基準にする
まとめ
- コメント → なぜそう書いたかを補足する
- Docstring → 関数やクラスの使い方を説明する公式文書
- 書きすぎる必要はなく、コードと説明の整合性を保つことが最重要
