---
paths: ["lib/**", "test/**"]
---

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

本ドキュメントでは，SmTIAS-Capture プロジェクトの Dart / Flutter コーディング規約（命名・フォーマット・import・型・コメント）を定義する．
基本方針として [Effective Dart](https://dart.dev/effective-dart) に準拠し，プロジェクト固有のルールのみ本書で定める．

※ ディレクトリ構成・ファイル配置は [project-structure ルール](project-structure.md)，エラー処理・ログは [error-handling ルール](error-handling.md) を参照する．

## フォーマット (Formatting)

- `dart format` のデフォルト設定に従う（行幅 80 文字）
- VS Code の「保存時フォーマット」を有効にする（`.vscode/settings.json` で設定済み）
- 手動でのフォーマット調整は行わない

## 命名規則 (Naming Conventions)

Effective Dart の命名規則に従う．プロジェクト固有の補足は以下の通り．

| 対象 | 規則 | 例 |
| --- | --- | --- |
| ファイル名 | snake_case | `camera_provider.dart` |
| クラス名 | UpperCamelCase | `CameraProvider` |
| 変数・関数 | lowerCamelCase | `takePhoto()` |
| 定数 | lowerCamelCase | `defaultImageQuality` |
| プライベート | 先頭に `_` | `_controller` |
| Provider | `〇〇Provider` | `CameraProvider` |
| Service | `〇〇Service` | `FileService` |
| Screen（画面） | `〇〇Screen` | `CaptureScreen` |
| Widget（部品） | 機能を表す名前 | `ShutterButton` |

## import 順序 (Import Order)

以下の順序で記述し，各グループ間は空行で区切る．

```dart
// 1. Dart SDK
import 'dart:async';
import 'dart:io';

// 2. Flutter SDK
import 'package:flutter/material.dart';

// 3. 外部パッケージ（pub.dev）
import 'package:camera/camera.dart';
import 'package:provider/provider.dart';

// 4. プロジェクト内
import 'package:smtias_capture/providers/camera_provider.dart';
import 'package:smtias_capture/services/file_service.dart';
```

※ `dart fix --apply` および `dart format` で自動整列されるため，手動調整は不要．

## 型の使い方 (Type Usage)

- ローカル変数は型推論（`var` / `final`）を活用する
- 関数の引数・戻り値には明示的に型を記述する
- `dynamic` は避け，`Object?` を使用する
- `final` をデフォルトとし，再代入が必要な場合のみ `var` を使用する

## ドキュメント (Documentation)

### コード内コメント

- **DartDoc コメント（`///`）**: 公開 API（public なクラス・メソッド）に記述する
- **実装コメント（`//`）**: ロジックが自明でない箇所にのみ記述する
- 「何をしているか」ではなく「なぜそうしているか」を書く

### DartDoc の書き方

```dart
/// 撮影画像を PNG 形式で共有ストレージに保存する．
///
/// [imageBytes] は JPEG エンコード済みの画像データ．
/// 保存先は `Pictures/MiniTIAS/` ディレクトリ．
/// 同秒の重複ファイルが存在する場合は連番サフィックスを付与する．
Future<String> saveImage(Uint8List imageBytes) async {
  // ...
}
```

- 1 行目は動詞で始める簡潔な要約（句点で終わる）
- 詳細が必要な場合は空行を挟んで続ける
- パラメータの説明は `[paramName]` 記法を使用する