# Comment Detailed

> Pythonファイルの挙動を理解するために、挙動を変えずに解説コメントとdocstringを追加する。ユーザーが「XXX.pyについて、動作を理解したいから細かくコメント入れて」「挙動は変えずにコメントを足して」「このPythonファイルに解説を入れて」などと言ったときに使う。

- Skill: `majiayu000/comment-detailed` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/comment-detailed`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/comment-detailed/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/comment-detailed

---


# Comment detailed

## 目的

- 対象の `*.py` を「読むだけで追える」状態にするため、コメント/Docstring を追加する。
- **コードの挙動は変えない（コメントのみ）**。
- **コメント追加に際し、md ファイルでユーザーへの事前確認は不要**

## ワークフロー

### 1) 対象ファイルを確定する

- ユーザーがパスを出していない場合は、対象ファイルのパス（または該当コード）を要求する。
- 既存コメント/Docstring の言語・流儀が明確ならそれに合わせる。無ければ日本語で書く。

### 2) 全体像を把握する

- このファイルの役割（責務）を 1〜2 文で言える状態にする。
- 入力/出力/副作用（I/O・グローバル状態・乱数・時刻・環境変数など）を把握する。
- “入口” を特定する（公開 API、`main()`、CLI、コールバック、テストからの呼び出し等）。

### 3) コメントを追加する（上から順に）

- **モジュール先頭 Docstring**
  - 目的、入力/出力、副作用、主要依存、主要フロー（読む順番）を書く。
- **主要クラス/関数の Docstring**
  - 責務、引数、戻り値、例外（投げる/握りつぶす）、副作用、前提/不変条件を書く。
  - 既に docstring がある場合は、重複を避けて「不足だけ」を追記する。
- **難所の inline コメント**
  - 「何をしているか」より「なぜそうするか / 何を前提にしているか」を優先する。
  - ループや分岐は、境界条件・不変条件・単位（ms/s、px、rad/deg、座標系など）を明記する。

### 4) 書き方の基準（Do / Don’t）

- Do: 意図、前提、制約、落とし穴、例外系、性能上の理由を書く。
- Do: “読む順番” が分かるように、上流 → 下流の流れで情報を配置する。
- Don’t: 変数名や関数名から自明な「逐語説明」をしない。
- Don’t: 未確定の推測をコード内コメントで断定しない（必要なら返信の「要確認」にまとめる）。

### 5) セルフチェック（挙動変更なし）

- 差分がコメント/Docstring のみであることを確認する。
- import・式・条件・順序・名前を変えていないことを確認する。
- 空白や整形の大規模変更は避け、必要なら理由を添える。

### 6) 可能なら軽い検証

- 可能なら `python -m py_compile <file>` を実行し、失敗したらその内容を報告する。
- 近くにテストがある場合は、プロジェクトの方針に従って最小限のテストを実行する。

## 返答フォーマット（推奨）

- 追加したコメントの狙い（3〜6 点）
- 重点的に追記した箇所（関数/クラス名）
- 要確認（不明点が残る場合のみ）