5-2 コーディング規約
Coding Standards
1. コーディング規約の目的
1.1 なぜ規約が必要か
コーディング規約は、チーム開発において品質と一貫性を保つための基盤である。 規約がないと、開発者ごとにスタイルが異なり、 コードの可読性が低下し、保守が困難になる。 また、コードレビューでスタイルの議論に時間を取られ、 本質的な問題の指摘が疎かになりがちである。
| 目的 | 効果 |
|---|---|
| 可読性の向上 | 誰が書いても読みやすいコード |
| 保守性の向上 | 変更・修正が容易 |
| バグの防止 | 危険なパターンを禁止 |
| レビューの効率化 | スタイルの議論を排除 |
| オンボーディング | 新メンバーの学習コスト削減 |
1.2 規約の適用範囲
コーディング規約は、命名規則、フォーマット、コメントなど 複数のカテゴリにわたって定義される。 命名規則は変数や関数の名前のつけ方を定め、 フォーマットはインデントや空白のルールを定める。 コメントの書き方やドキュメントの形式も重要な要素である。
| カテゴリ | 内容 |
|---|---|
| 命名規則 | 変数、関数、クラスなどの名前のつけ方 |
| フォーマット | インデント、空白、改行、括弧の位置 |
| コメント | コメントの書き方、ドキュメント |
| 構造・設計 | 関数の長さ、クラスの責務 |
| 禁止パターン | 使用禁止の構文、危険なパターン |
2. 命名規則
2.1 命名スタイル
命名スタイルは言語やコミュニティによって慣習が異なる。 camelCaseはJavaScriptやJavaで変数・関数に使われ、 PascalCaseはクラス名に使われることが多い。 Pythonではsnake_caseが標準的であり、 定数にはUPPER_SNAKE_CASEを使用する。 プロジェクト内で一貫したスタイルを使用することが重要である。
| スタイル | 例 | 一般的な用途 |
|---|---|---|
| camelCase | getUserName | 変数、関数（JavaScript、Java） |
| PascalCase | UserAccount | クラス、型 |
| snake_case | user_name | 変数、関数（Python、Ruby） |
| UPPER_SNAKE_CASE | MAX_VALUE | 定数 |
| kebab-case | user-profile | URL、CSSクラス |
2.2 良い命名の原則
良い命名はコードの可読性を大きく左右する。 名前は意図を表し、発音可能で、検索可能であるべきである。 略語は避け、チーム内で一貫した用語を使用する。 良い命名はコメント以上の価値があり、 名前から「このコードは何をしているか」が読み取れれば、 コメントは最小限で済む。
| 原則 | 悪い例 | 良い例 |
|---|---|---|
| 意図を表す | d, temp, data | elapsedDays, userInput |
| 発音可能 | genymdhms | generationTimestamp |
| 検索可能 | 7, e | MAX_CLASSES, event |
| 略語を避ける | usr, cnt, mgr | user, count, manager |
| 一貫性 | fetch/get/retrieve混在 | getXxx で統一 |
良い命名はコメント以上の価値がある。 「このコードは何をしているか」が名前から読み取れれば、 コメントは最小限で済む。
3. フォーマット規則
3.1 インデントと空白
フォーマットの一貫性は可読性に直結する。 インデントはスペース2つまたは4つが一般的で、タブは避けることが多い。 行の長さは80〜120文字に制限し、長い行は適切に改行する。 演算子やカンマの前後にスペースを入れることで、コードが読みやすくなる。
| 項目 | 一般的なルール |
|---|---|
| インデント | スペース2つまたは4つ |
| 行の長さ | 80〜120文字以内 |
| 演算子の前後 | スペースを入れる |
| カンマの後 | スペースを入れる |
| 空行 | 関数間、論理ブロック間に1行 |
3.2 自動フォーマッタ
フォーマットの議論を排除するために、自動フォーマッタを導入する。 PrettierはJavaScriptやTypeScriptで広く使われており、 Pythonでは「妥協のないフォーマッタ」Blackが人気である。 Go言語のgofmtは言語標準で提供されている。 コミット前に自動フォーマットを実行する設定（pre-commitフック）を 導入することで、フォーマット違反を防止できる。
| ツール | 対象言語 |
|---|---|
| Prettier | JavaScript、TypeScript、CSS |
| Black | Python |
| gofmt | Go |
| rustfmt | Rust |
フォーマッタの導入効果
コードレビューでスタイルの指摘がなくなり、本質的な議論に集中できる。 コミット前に自動フォーマットを実行する設定を 導入することで、フォーマット違反を防止できる。
4. コメントとドキュメント
4.1 コメントの原則
コメントは「Why（なぜ）」を書くべきであり、 「What（何を）」は避けるべきである。 コードが何をしているかは読めばわかるが、 なぜそのような実装にしたかは読み取れないことが多い。 ただし、コメントはコードと同期しないと嘘をつくことになるため、 コード変更時には必ずコメントも見直す必要がある。
| 原則 | 説明 |
|---|---|
| Whyを書く | コードが「なぜ」そうなっているか |
| Whatは避ける | コードが「何をしているか」は読めばわかる |
| 最新に保つ | コード変更時にコメントも更新 |
| 冗長を避ける | 自明なコードにコメントは不要 |
4.2 ドキュメントコメント
公開APIには、ドキュメントコメントを記述する。 Javaではjavadoc形式、Pythonではdocstring、 JavaScriptではJSDoc形式が標準的である。 これらのコメントからAPIドキュメントを自動生成できる。
| 言語 | 形式 | ツール |
|---|---|---|
| Java | Javadoc | javadoc |
| Python | docstring | Sphinx |
| JavaScript | JSDoc | JSDoc |
最悪のコメントは、コードと一致しないコメントである。 コードを変更したらコメントも必ず見直すこと。 コメントがなくても理解できるコードを書くことが理想。
5. 静的解析ツール
5.1 リンター（Linter）
リンターは、コーディング規約違反や潜在的なバグを検出するツールである。 ESLintはJavaScript/TypeScriptで最も広く使われており、 ルールのカスタマイズが豊富である。 PythonではPylintやFlake8がPEP8準拠をチェックする。 IDEと統合することで、リアルタイムで違反を検出できる。
| ツール | 対象言語 | 特徴 |
|---|---|---|
| ESLint | JavaScript、TypeScript | ルールのカスタマイズが豊富 |
| Pylint / Flake8 | Python | PEP8準拠チェック |
| RuboCop | Ruby | Rubyスタイルガイド準拠 |
| Checkstyle | Java | Javaコーディング規約チェック |
5.2 CI/CDでの静的解析
CI/CDパイプラインに静的解析を組み込むことで、 規約違反をマージ前に検出できる。 SonarQubeやCodeClimateは多言語対応で、 品質ゲートを設定してマージを制御できる。 これにより、技術的負債の蓄積を防ぐことができる。
| サービス | 特徴 |
|---|---|
| SonarQube / SonarCloud | 多言語対応、品質ゲート |
| CodeClimate | 技術的負債の可視化 |
| Codacy | 自動コードレビュー |
コーディング規約を学んだら、次は「5-3 コードレビュー」で 品質を高めるレビュープロセスについて学習しよう。
[1] Martin, R. C. (2008). Clean Code.
[2] Google. Google Style Guides.