========================================================================
コードコメント・ドキュメント規則 (Code Comment & Documentation Guide)
========================================================================


1. 基本方針 (Basic Policy)
------------------------------------------------------------------------
コードの可読性と保守性を高めるため，ファイル・クラス・関数・定数それぞれに対して
適切な粒度でコメントを記述する．
※ コードの書き方自体の規則は `GUIDE_04_コーディング規則.txt` を参照する．

・言語: 日本語で記述する．
・句読点: 「，」（全角カンマ）を使用し，文末の句点（「．」「。」）は付けない．
    - 列挙が続く場合は「，」で区切る．
・文体: 体言止め，または「〜する」形で統一する．
・更新: コードを変更した場合は，対応するコメントも必ず合わせて更新する．
    - コードと乖離したコメントは誤解を招くため，古いまま放置しない．


2. コメントの種類と用途 (Comment Types)
------------------------------------------------------------------------

2-1. ファイルドキュメント (Module Docstring)
    ・ファイルの先頭に必ず記述する．
    ・トリプルダブルクォート（`""" """`）を使用する．
    ・書式:

        """
        [ファイル名（拡張子なし）]
        [ファイルの主な責務を1行で説明]
        [補足情報があれば続けて記述]
        """

    ・例:

        """
        motor_controller
        モーターの制御を担当するモジュール
        GPIO を介して左右のモーターの速度・方向を制御する
        """

2-2. クラスドキュメント (Class Docstring)
    ・全てのクラスに記述する．
    ・クラス定義の直後にトリプルダブルクォートで記述する．
    ・書式:

        class ClassName:
            """[そのクラスが何を表すかを端的に説明]"""

    ・複数行が必要な場合:

        class ClassName:
            """
            [そのクラスが何を表すかを端的に説明]
            [補足情報]
            """

    ・例:

        class MotorController:
            """左右のモーターを GPIO 経由で制御するクラス"""

2-3. 関数・メソッドドキュメント (Function Docstring)
    ・公開関数・メソッドには必ず記述する．
    ・Google スタイルの docstring を使用する．
    ・書式:

        def function_name(arg1: type, arg2: type) -> return_type:
            """[その関数が何をするかを端的に説明]

            Args:
                arg1: [説明]
                arg2: [説明]

            Returns:
                [返り値の説明]
            """

    ・引数・返り値がない，または自明な場合は1行で省略してよい．

        def stop(self) -> None:
            """全モーターを停止する"""

    ・例外をスローする可能性がある場合は `Raises` セクションを付ける．

        def set_speed(self, speed: int) -> None:
            """モーターの速度を設定する

            Args:
                speed: 0〜100 の範囲の速度値

            Raises:
                ValueError: speed が 0〜100 の範囲外の場合
            """

    ・廃止予定のものには非推奨であることを明記し，代替を示す．

        def old_method(self) -> None:
            """非推奨: new_method を使用すること"""

    ・例:

        def calc_distance(speed: float, duration: float) -> float:
            """速度と時間から距離を計算する

            Args:
                speed: 移動速度 (m/s)
                duration: 経過時間 (s)

            Returns:
                移動距離 (m)
            """
            return speed * duration

2-4. 定数ドキュメント (Constant Comment)
    ・公開される定数にはインラインコメント（`#`）を直前行に記述する．
    ・書式:

        # [その定数が何を表すかを端的に説明]
        CONSTANT_NAME = value

    ・例:

        # UI側と共有する最大速度の既定値
        MAX_SPEED = 100

        # 超音波センサーの測定間隔 (秒)
        SENSOR_INTERVAL_SEC = 0.5

2-5. ブロックコメント (Block Comment)
    ・関数・メソッド内で，処理のまとまりが変わる箇所に記述する．
    ・`#` + 半角スペースを使用する．
    ・書式:

        # [このブロックの処理を端的に説明]
        ...処理...

    ・例:

        # 入力値を正規化する
        normalized = raw_value / MAX_VALUE

        # モーターに速度を反映する
        GPIO.output(self._pin, normalized)

2-6. タスクコメント (Task Comment)
    ・後で対応が必要な箇所に記述し，担当者と内容を明記する．
    ・`#` + 半角スペースを使用し，以下のタグで種別を区別する．
    ・書式:

        # [タグ]([担当者名]): [内容]

    ■ タグ定義:
    - TODO  : 将来的に実装・対応が必要な箇所
    - FIXME : 既知のバグや不具合があり修正が必要な箇所
    - HACK  : 意図的な暫定対応であり，本来あるべき実装ではない箇所

    ・例:

        # TODO(yamada): タイムアウト処理を実装する
        # FIXME(tanaka): 距離が負になるケースでクラッシュする
        # HACK(suzuki): API仕様確定まで固定値で代替している

    ・注意:
        - 「いつか直す」ではなく，必ずタスク管理ツールとセットで運用する
        - FIXME はリリース前に必ず解消する
        - HACK は技術的負債として定期的に見直す


3. 記述しない場合の判断基準 (When to Omit)
------------------------------------------------------------------------
・ファイル内部でのみ使用し，外部に公開されない関数・定数は省略してもよい
・コード自体が自明な場合（変数名で意図が十分伝わる場合）は省略してもよい
・ユニットテストファイルは，テストケース名で意図が伝わる場合は省略してもよい


4. NG例 (Anti-patterns)
------------------------------------------------------------------------
・句点を付ける
    - NG: """ジョイスティックの入力を受け取る．"""
    - OK: """ジョイスティックの入力を受け取る"""

・「、」「。」を使う
    - NG: # 入力開始時の基準座標をセットする。
    - OK: # 入力開始時の基準座標をセットする

・コードをコメントアウトして残す
    - NG: # old_handler = lambda: ...
    - OK: 不要なコードは削除する（Git履歴から復元できる）

・docstring を通常のコメントで書く
    - NG: # motor_controller: モーターの制御を担当するモジュール
    - OK:
        """
        motor_controller
        モーターの制御を担当するモジュール
        """