---
paths: ["src/**", "scripts/**"]
---

# コーディング規約 (Coding Standards)

Python コード（`src/**`・`scripts/**`）を編集するときは本ルールに従うこと．

## 基本方針 (Basic Policy)

- ruff を唯一の lint / format ツールとして使用する．設定は `pyproject.toml` の `[tool.ruff]` に集約．
- 標準（PEP 8 + Effective Python）から逸脱しない範囲で，ruff の自動修正に従う．
- プロジェクト固有のルールはこのファイルに最小限で書く．
- 別ツール（black, isort, mypy 等）は導入しない（ruff で完結）．

## 適用 ruff ルール

`pyproject.toml` の `[tool.ruff.lint]` で `select = ["E", "F", "W", "I", "B", "UP", "N"]` を選択．

| ルール | 内容 |
| --- | --- |
| E (pycodestyle) | PEP 8 形式エラー |
| F (pyflakes) | 未使用変数・未定義シンボル等 |
| W (pycodestyle) | 形式警告 |
| I (isort) | import 文の並び順 |
| B (flake8-bugbear) | バグになりやすいパターン検出 |
| UP (pyupgrade) | Python 3.12 機能で書き換え可能なコードの提案 |
| N (pep8-naming) | クラス・関数・変数命名 |

行長は 100 文字（Mitsuba API や数式リテラルが長くなりがちなため）．

実行コマンド：

```powershell
uv run ruff check .          # 検査のみ
uv run ruff check . --fix    # 自動修正
uv run ruff format .         # フォーマット適用
```

## 型ヒント (Type Hints)

- **公開関数（モジュールから export される関数・クラス）**: 引数と戻り値に型ヒント必須
- **内部ヘルパ・テストコード**: 任意．書ける所は書く
- **Mitsuba / Dr.Jit の戻り値**: 型ヒントが不完全．`Any` または `np.ndarray` でフォールバック可

例：

```python
import numpy as np


def to_grayscale(image: np.ndarray) -> np.ndarray:
    """RGB → 輝度変換．..."""
    ...
```

静的型チェック（mypy / pyright）は当面導入しない．必要が出てから追加．

## docstring

- **公開関数・クラス**: docstring 必須
- **書式**: Google スタイル（`Args:` / `Returns:` / `Raises:`）に統一
- **言語**: 日本語可．数式は LaTeX 表記（`$Y = 0.2126 R + ...$`）を許可
- **数式の出典**: 引用 `[1]` を残し，参考文献は同モジュールの末尾コメントまたは docstring 末尾に列挙

例：

```python
def to_grayscale(image: np.ndarray) -> np.ndarray:
    """RGB 画像を Rec.709 輝度係数でグレースケールに変換する [1]．

    $Y = 0.2126 R + 0.7152 G + 0.0722 B$

    Args:
        image: 入力 RGB 画像（H x W x 3, uint8）．

    Returns:
        輝度画像（H x W, float64, 値域 0.0〜255.0）．

    References:
        [1] ITU-R BT.709
    """
```

## 命名規則 (Naming)

ruff `N` ルールでチェック．

| 対象 | スタイル | 例 |
| --- | --- | --- |
| モジュール | snake_case | `uniformity.py`, `scene_builder.py` |
| パッケージ | snake_case | `sm_tias_lightsim` |
| 関数・変数 | snake_case | `to_grayscale`, `roi_image` |
| クラス | PascalCase | `SceneBuilder`, `LedLight` |
| 定数 | UPPER_SNAKE_CASE | `REC709_COEFF_R` |
| プライベート | 接頭辞 `_` | `_validate_roi` |

## コメント

- **WHY を書く**：何をしているかは識別子で表現．コメントは「なぜこの実装か」「数式の出典」「制約」に限定する．
- **TODO** は `# TODO(rintoHasegawa): 内容` 形式で記述する．

## import 順序

ruff `I` で自動整列．以下の順：

1. 標準ライブラリ
2. サードパーティ（`mitsuba`, `numpy`, `trimesh` 等）
3. プロジェクト内（`from sm_tias_lightsim import ...`）

手動整列不要．

## CLI 引数

- 短縮形より長い形を優先（`--scene` を主，`-s` は併用）
- `argparse` 標準を使用
- ヘルプ文は日本語可

## エラー処理

- 例外の使い分け・方針は `.claude/rules/error-handling.md` に定義する（`src/**`・`scripts/**` 編集時に自動ロードされる）．

## 参考 (References)

- [PEP 8 — Style Guide for Python Code](https://peps.python.org/pep-0008/)
- [Google Python Style Guide — Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
- [ruff documentation](https://docs.astral.sh/ruff/)