python-comments

Python コメント

目的

Python コードのコメントには、次の 2 つの運用モードがあります。

1. 作成モード - 不足しているコメントを追加し、既存のコメントを改善し、否定的なタイプのコメントを修正します
2. 監査モード - すべてのコメントを分類し、不足箇所を特定し、構造化された品質レポートを作成します

基本原則：コメントは なぜ を説明し、コードは 何を するかを説明します。型ヒントは 型 を説明します。

呼び出すタイミング

作成モードのトリガー：

• ユーザーが「コメントを追加して」「これをドキュメント化して」「コメントを改善して」と依頼した場合
• コードレビューで docstring の不足や不明瞭なロジックが指摘された場合
• 新しいモジュール／クラス／関数にドキュメントがない場合
• 複雑なアルゴリズムやビジネスルールに説明が必要な場合

監査モードのトリガー：

• ユーザーが「コメントをレビューして」「コメントの品質」「ドキュメントの監査」と依頼した場合
• リリース前のドキュメントレビュー
• 新しいチームメンバーのオンボーディング準備
• レガシーコードの評価

呼び出さないタイミング

• コードの削除が予定されている場合
• ユーザーが API リファレンスの生成を希望している場合（代わりにドキュメントツールを使用してください）
• ユーザーが型スタブの生成を希望している場合（代わりに型ヒントツールを使用してください）
• コメントを追加しても価値のない、単純なスクリプトや一度限りのスクリプト

Python 向け Antirez コメント分類

antirez の「Writing system software: code comments」で示されている 9 種類のコメントです。詳細は references/taxonomy.md を参照してください。

肯定的なタイプ（これらを書く）

タイプ	名前	Python での形式	目的
1	関数	Docstring	関数／クラス／モジュールが何をするか
2	設計	Docstring または #	アーキテクチャの根拠、API 設計上の選択
3	理由	インライン #	コードの自明でない理由
4	解説	インライン #	ドメイン知識、アルゴリズムの説明
5	チェックリスト	インライン #	省略したり順序を変えたりしてはいけない手順
6	ガイド	# セクション見出し	長いモジュール内のナビゲーション補助

否定的なタイプ（検出して修正する）

タイプ	名前	検出方法	修正
7	自明	コードを言い換えている	削除
8	負債	TODO、FIXME、HACK	解決するか、課題を作成する
9	バックアップ	コメントアウトされたコード	削除（履歴は git に保存されています）

Python 固有の対応関係

Docstring とインラインコメント

• Docstring（"""..."""） - タイプ 1～2。インターフェース（何をするか、引数、戻り値、例外）を説明します。PEP 257 に従ってください。
• インラインコメント（#） - タイプ 3～6。実装（理由、方法、背景）を説明します。
• 型ヒント - コメントの負担を軽減します。docstring では型ではなく、意味を記述してください。

型ヒントでコメントの負担を軽減する

# BAD: Comment duplicates type hint
def process(data: list[dict]) -> bool:
    """Process data.

    Args:
        data: A list of dictionaries  # Redundant - type hint says this
    """

# GOOD: Docstring adds semantic meaning
def process(data: list[dict]) -> bool:
    """Process sensor readings and flag anomalies.

    Args:
        data: Sensor readings keyed by timestamp, each containing
              'value', 'unit', and optional 'calibration_offset'
    """

PEP 257 の要点

• 1 行の docstring："""Return the user's full name."""（命令形、ピリオドで終える）
• 複数行：要約行、空行、詳細な説明
• すべての公開モジュール、クラス、関数、メソッドに docstring が必要です
• プライベートメソッド：ロジックが自明でない場合は docstring を記述します

作成モードのワークフロー

4 つのフェーズで実行します。

フェーズ 1：スキャン

1. コメントを付けるファイル／モジュール全体を読みます
2. 既存のコメントと docstring をすべて特定します
3. コード構造を把握します：モジュール、クラス、関数、複雑なブロック
4. すでにある型ヒントを確認します（docstring の負担を軽減します）

出力： 既存のドキュメントとコード構造の一覧。

フェーズ 2：不足点を分類する

各コード要素について、何が不足しているかを判断します。

1. モジュールレベル - モジュールの docstring が不足していますか？セクションのガイドコメントが不足していますか？
2. クラスレベル - クラスの docstring が不足していますか？設計上の根拠が不足していますか？
3. 関数レベル - docstring が不足していますか？パラメーターの意味が不足していますか？複雑なロジックに理由を説明するコメントが不足していますか？
4. ブロックレベル - 複雑なアルゴリズムに解説コメントがありませんか？自明でない条件に理由を説明するコメントがありませんか？複数の手順からなる処理にチェックリストコメントがありませんか？

影響度に基づいて不足点に優先順位を付けます。

• 重大 - docstring のないパブリック API、説明のない複雑なアルゴリズム
• 高 - 理由を説明するコメントのない自明でないビジネスルール、チェックリストのない複数手順の処理
• 中 - 長いモジュールにガイドコメントがない、設計上の根拠が不足している
• 低 - docstring のないプライベートヘルパー（ロジックが明白なら省略）

出力： 必要なコメントの種類を含む、優先順位付きの不足点リスト。

フェーズ 3：記述する

以下のルールに従ってコメントを追加します。

1. 適切な種類を選ぶ - フェーズ 2 の分類で使用した分類体系に従います
2. 適切な形式を選ぶ - 種類 1～2 には docstring、種類 3～6 にはインライン # を使用します
3. 適切なスタイルを選ぶ - プロジェクトで既存の docstring スタイルに合わせます。指定がない場合は Google スタイルを使用します。references/docstring-styles.md を参照してください
4. 簡潔に記述する - すべての語句に意味を持たせます
5. 否定的なコメントを解消する - 些細なコメント（種類 7）を削除し、負債を解消するか課題として記録し（種類 8）、バックアップコード（種類 9）を削除します

種類ごとの記述ルール：

• 種類 1（関数）： 命令形を使用します。目的、引数の意味（型ヒントがある場合は型を除く）、戻り値、例外、副作用を記述します。references/docstring-styles.md を参照してください
• 種類 2（設計）： 他の方法ではなく、この方法を選んだ理由を説明します。モジュールまたはクラスのレベル、あるいは複雑な関数の上に記述します
• 種類 3（理由）： 自明でないコードの直前に1行で記述します。「何をするか」ではなく「なぜそうするか」から始めます
• 種類 4（解説）： ドメインの概念またはアルゴリズムを説明します。該当する場合は外部の参考資料にリンクします
• 種類 5（チェックリスト）： 手順に番号を付けます。順序に依存する手順にはその旨を明記します。省略した場合に何が問題になるかを記載します
• 種類 6（ガイド）： 長いモジュールではセクション見出しを使用します。# --- Section Name --- または # region／# endregion を使用します

出力： コメントを追加したコード。

フェーズ 4：検証する

1. 些細なコメントを追加していないこと - すべてのコメントがコードにない情報を補っている
2. 種類を重複させていないこと - docstring が型ヒントを繰り返していない
3. スタイルが一貫していること - すべての docstring が同じスタイル（Google／NumPy／Sphinx）に従っている
4. 既存のコメントが保持されていること - 明示的に否定的な種類に該当する場合を除き、有効な既存のコメントを削除していない
5. コードが変更されていないこと - 変更したのはコメント／docstring のみで、ロジックに変更がない

出力： すべてのチェックに合格した、最終的なコメント付きコード。

監査モードのワークフロー

4つのフェーズを実行します。

フェーズ 1：収集する

1. 対象コードからすべてのコメントと docstring を抽出します
2. 場所（ファイル、行、スコープ）を記録します
3. 形式（docstring、インライン #、ブロック #）を記録します
4. 関連するコード要素（モジュール、クラス、関数、ブロック）を記録します

出力： 場所を含むコメント一覧。

フェーズ 2：分類する

各コメントに以下を割り当てます。

• 種類（分類体系の 1～9）
• 品質（良好／適切／不良）
• 正確性（正確／古い／誤解を招く）

種類ごとの品質基準の詳細は references/taxonomy.md を参照してください。

• 種類 1（関数）：目的、引数、戻り値、例外を網羅しているか。命令形になっているか。
• 種類 2（設計）：根拠を説明しているか。検討した代替案に言及しているか。
• 種類 3（理由）：コードを言い換えるだけでなく、理由を説明しているか。
• 種類 4（解説）：ドメインに関する説明が正確か。出典へのリンクがあるか。
• 種類 5（チェックリスト）：手順に番号が付いているか。省略した場合の影響が記載されているか。
• 種類 6（ガイド）：形式が一貫しているか。実際のコードのセクションに合っているか。
• 種類 7（些細）：削除候補
• 種類 8（負債）：実行可能な解決策が示されているか。
• 種類 9（バックアップ）：削除候補

出力： 品質評価を含む、分類済みコメント一覧。

フェーズ 3：ギャップ分析

不足している点を特定します：

1. 公開 API のカバレッジ - docstring が記載されている公開関数／クラス／モジュールの割合
2. 理由コメントのカバレッジ - 自明でない理由を説明するコメントが付いた複雑なロジックブロックの割合
3. 設計ドキュメント - モジュール／クラスレベルで文書化されたアーキテクチャ上の決定
4. 否定的なコメントの数 - 些末なコメント、負債となるコメント、バックアップコメントの数

重大度レベル：

• Critical - docstring のない公開 API、誤解を招くコメント
• High - 理由コメントのない複雑なロジック、古くなったコメント
• Medium - 設計根拠の不足、ガイドコメントの不足
• Low - docstring のない非公開メソッド、軽微なスタイルの不統一

出力： 重大度評価付きのギャップ分析。

フェーズ 4：レポート

構造化された監査レポートを生成します。

監査レポートの形式

## Comment Audit Report

### Summary
- **Files analyzed:** N
- **Total comments:** N (docstrings: N, inline: N)
- **Comment density:** N comments per 100 LOC
- **Type distribution:** Type 1: N, Type 2: N, ... Type 9: N
- **Quality score:** N/10

### Critical Gaps
- [ ] {file}:{line} - {element} - Missing {type} comment - {impact}

### Issues Found
#### Negative Comments (fix or remove)
- {file}:{line} - Type {N} ({name}) - "{comment text}" - Action: {delete/resolve/rewrite}

#### Outdated Comments
- {file}:{line} - "{comment text}" - Mismatch: {description}

#### Quality Issues
- {file}:{line} - Type {N} - Issue: {description}

### Coverage Metrics
| Scope | With Docstring | Without | Coverage |
|-------|---------------|---------|----------|
| Modules | N | N | N% |
| Classes | N | N | N% |
| Public functions | N | N | N% |
| Public methods | N | N | N% |

### Recommendations
1. **Priority 1:** {action} - {N elements affected}
2. **Priority 2:** {action} - {N elements affected}
3. **Priority 3:** {action} - {N elements affected}

### Comment Style
- **Detected style:** {Google/NumPy/Sphinx/mixed}
- **Consistency:** {consistent/inconsistent}
- **Recommendation:** {standardize on X style}

レポートの完全な例については、references/examples/audit-mode-examples.md を参照してください。

主な制約

• 些末なコメントは絶対に追加しないでください - コードに x += 1 とある場合、# increment x を追加しないでください
• プレースホルダーの docstring は絶対に追加しないでください - 複雑な関数に """Process data.""" を記載するのは、何も記載しないより悪いことです
• 型ヒントと重複させないでください - 型ヒントがある場合は、型ではなく意味を説明してください
• コードのロジックは絶対に変更しないでください - コメントと docstring のみを対象とし、機能上の変更は一切行いません
• 既存のスタイルを維持してください - プロジェクトで使われている docstring のスタイルに合わせてください
• 有効なコメントは維持してください - 否定的なタイプ（7～9）に該当するコメント、または明らかに誤っているコメントのみを変更または削除してください

同じパッケージ内のスキルとの連携

• python-refactor-method - リファクタリングに伴いコメントの更新が必要になる場合があります。リファクタリング後に write モードを実行して docstring を更新してください
• pytest-patterns - テストの docstring にはタイプ 1（関数）コメントが役立ちます。audit モードではテストのドキュメントを評価できます
• python-performance-optimization - パフォーマンスが重要なコードでは、アルゴリズムの選択理由を説明するタイプ 4（教師）コメントが役立ちます
• python-packaging - パッケージレベルのドキュメント（__init__.py の docstring）には、タイプ 1＋2 のパターンを使用します