tomevault-io 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 点）
- 重点的に追記した箇所（関数/クラス名）
- 要確認（不明点が残る場合のみ）
Converted and distributed by TomeVault — claim your Tome and manage your conversions.