言語に依存しないコーディング原則

核となる哲学

1. 速度より保守性: 初期開発の速度よりも長期的なコード品質を優先する
2. シンプルさを最優先: 要件を満たす最もシンプルなソリューションを選択する(YAGNI原則)
3. 明示的より暗黙的: コード構造と命名を通じて意図を明確にする
4. コメントより削除: コードをコメントアウトするのではなく、不要なコードを削除する

コード品質

継続的改善

• 各変更セット内で関連コードをリファクタリング — 修正中のファイルのスタイル、命名、構造の問題に対処する
• コード構造を段階的に改善する
• コードベースを軽量で焦点を絞った状態に保つ
• 不要なコードはすぐに削除する

可読性

• 問題領域から引き出した意味のある記述的な名前を使用する
• 名前には完全な単語を使用する。省略形は領域内で広く認識されている場合のみ許容される
• 記述的な名前を使用する。単一文字の名前はループカウンタまたは一般的な慣例(i、j、x、y)の場合のみ許容される
• マジックナンバーと文字列を名前付き定数に抽出する
• 可能な限りコードが自己説明的であるようにする

関数設計

パラメータ管理

• 推奨: 関数あたり0〜2個のパラメータ
• 3個以上のパラメータの場合: オブジェクト、構造体、辞書を使用して関連パラメータをグループ化する
• 例(概念的):

  // Instead of: createUser(name, email, age, city, country)
  // Use: createUser(userData)
  

単一責任

• 各関数は1つのことをよく実行する
• 関数は小さく焦点を絞った状態を保つ(通常50行未満)
• 複雑なロジックを個別の名前付き関数に抽出する
• 関数は1つの抽象レベルを持つべき

関数の構成

• 可能な限りピュア関数(副作用なし)
• データ変換と副作用を分離する
• 早期リターンを使用してネストを減らす
• ネストを最大3レベルに保つ。より深いネストには早期リターンまたは抽出関数を使用する

エラーハンドリング

エラー管理原則

• 常にエラーを処理する: コンテキスト付きでログするか明示的に伝播させる
• 適切にログする: デバッグのためのコンテキストを含める
• 機密データを保護する: パスワード、トークン、個人識別情報をログからマスクまたは除外する
• 早期に失敗する: エラーをできるだけ早く検出して報告する

エラー伝播

• 言語に適したエラーハンドリング機構を使用する
• エラーを適切なハンドリングレベルに伝播させる
• 意味のあるエラーメッセージを提供する
• 再スローする際にエラーコンテキストを含める

依存関係管理

パラメータ化された依存関係によるルーズカップリング

• 外部依存関係をパラメータとして注入する(クラスのコンストラクタインジェクション、手続き型/関数型コードの関数パラメータ)
• 具体的な実装ではなく抽象化に依存する
• モジュール間の依存関係を最小化する
• モック可能な依存関係を通じたテストを容易にする

リファレンス代表性

採用前のリファレンス検証

既存コードからパターン、API、依存関係を採用する場合:

• IF 近くの2〜3個のファイルのみを参照している → THEN パターンが代表的であることを確認するため、採用前にリポジトリ全体の使用状況を確認する
• IF リポジトリに複数のアプローチが共存している → THEN 多数派のパターンを特定し、意図的に選択する — 最も近いものを選択することは不十分である
• IF 外部依存関係(ライブラリ、プラグイン、SDK)を採用している → THEN 同じ依存関係のリポジトリ全体での使用分布を検証する。リポジトリの状態のみからは適切なバージョンを判断できない場合は、エスカレーションする
• IF 既存のパターンに従っている → THEN 代替案が存在する場合、それに従う理由を述べる(例: 周囲のコードとの一貫性、破壊的変更の回避、調整された更新の保留中)

原則

近くのコードは調査の出発点であり、採用の十分な根拠ではない。リファレンスがリポジトリの慣例と現在のベストプラクティスを代表していることを使用前に検証する。

パフォーマンス考慮事項

最適化アプローチ

• まず測定する: 最適化する前にプロファイリングする
• アルゴリズムに焦点を当てる: アルゴリズムの複雑性 > マイクロ最適化
• 適切なデータ構造を使用する: アクセスパターンに基づいて選択する
• リソース管理: メモリ、接続、ファイルを適切に処理する

最適化の時期

• プロファイリングを通じて実際のボトルネックを特定した後
• パフォーマンスの問題が測定可能な場合
• 初期開発中ではなく、測定可能なボトルネックが特定された後に最適化する

コード構成

構造的原則

• 関連機能をグループ化: 関連コードを一緒に保つ
• 関心の分離: ドメインロジック、データアクセス、プレゼンテーション
• 一貫した命名: プロジェクト慣例に従う
• モジュール結合度: モジュール内の高い結合度、モジュール間の低い結合度

ファイル構成

• 1ファイルあたり1つの主要責任
• 関連関数/クラスの論理的グループ化
• アーキテクチャを反映した明確なフォルダ構造
• 「ゴッドファイル」を回避する(500行を超えるファイル)

コメント原則

コメント時期

• 「何」を説明する: コードが何をするかを説明する
• 「なぜ」を説明する: 決定の背後にある理由を明確にする
• 制限事項を記録する: 既知の制約またはエッジケースを文書化する
• APIドキュメント: パブリックインターフェースは明確なドキュメントが必要

コメント範囲

• 「何」と「なぜ」についてコメントしする。「どのように」はコード自体が伝える
• 履歴コンテキストをコメントではなくバージョン管理のコミットメッセージに記録する
• コメントアウトされたコードを削除する(必要な場合はgit履歴から取得する)
• コードが述べている内容を超えた情報を追加するコメントを書く

コメント品質

• 将来のコード変更に関係なく正確なままであるコメントを書く。日付、バージョン、一時的な状態への参照を避ける
• コードを変更する際にコメントを更新する
• 適切な文法とフォーマットを使用する
• 将来のメンテナ向けに書く

リファクタリングアプローチ

安全なリファクタリング

• 小さなステップ: 一度に1つの変更を行う
• 動作状態を維持: テストが成功した状態を保つ
• 動作を検証: 各変更後にテストを実行する
• 段階的改善: すぐに完璧さを目指さない

リファクタリングのトリガー

• コード重複(DRY原則)
• 関数が50行を超えている
• 複雑な条件ロジック
• 不明確な命名または構造

テスト考慮事項

テスト可能性

• 最初からテスト可能なコードを書く
• 隠れた依存関係を避ける
• 副作用を明示的に保つ
• パラメータ化された依存関係向けに設計する

テスト駆動開発

• 必要に応じて実装前にテストを書く
• テストは単純で焦点を絞った状態を保つ
• 実装ではなく動作をテストする
• テスト品質をプロダクションコードと同等に保つ

セキュリティ原則

セキュアなデフォルト

• 環境変数または専用シークレット管理ツールを通じて認証情報とシークレットを保管する
• すべてのデータベースアクセスにパラメータ化クエリ(プリペアドステートメント)を使用する
• 言語またはフレームワークで提供される確立された暗号化ライブラリを使用する
• 暗号的に安全な乱数生成器でセキュリティ上重要な値(トークン、ID、ノンス)を生成する
• 保存中および転送中の機密データを標準プロトコルで暗号化する

入出力の境界

• システムエントリポイントですべての外部入力を期待される形式、タイプ、長さで検証する
• 出力をレンダリングコンテキスト(HTML、SQL、シェル、URL)に適切にエンコードする
• エラー応答で呼び出し元に必要な情報のみを返す。詳細な診断はサーバー側でログする

アクセス制御

• ユーザーデータを処理または状態変更をトリガーするすべてのエントリポイントに認証を適用する
• エントリポイントだけでなく、各リソースアクセスの認可を検証する
• 操作に必要な権限のみを付与する(ファイル、データベース接続、APIスコープ)

ナレッジカットオフ補足(2026-03)

• OWASP Top 10:2025は症状から根本原因にシフト。「ソフトウェアサプライチェーンの失敗」(A03)と「例外条件の不適切な処理」(A10)を追加
• 最近の研究は、AI生成コードがアクセス制御ギャップの高い率を示していることを示唆している — 認証と認可を高優先度のレビュー対象とする
• OpenSSFは「AIコードアシスタント指示のためのセキュリティフォーカスガイド」を公開 — 一般的なアドバイスより言語固有で実行可能な制約を推奨
• 詳細な検出パターンについては references/security-checks.md を参照

ドキュメント

コードドキュメント

• パブリックAPIとインターフェースを文書化する
• 複雑な機能の使用例を含める
• モジュール用のREADMEファイルを保守する
• 対応する動作を変更するのと同じコミットでドキュメントを更新する

アーキテクチャドキュメント

• 高レベルの設計決定を文書化する
• 統合ポイントを説明する
• データフローと境界を明確にする
• トレードオフと検討した代替案を記録する

バージョン管理慣例

コミット慣例

• アトミックで焦点を絞ったコミットを行う
• 明確で記述的なコミットメッセージを書く
• 動作するコード(テストが成功)をコミットする
• 本番対応のコードのみをコミットする。環境変数またはシークレット管理ツールにシークレットを保管する

コードレビュー準備

• レビューをリクエストする前に自己レビューを行う
• 変更を焦点を絞ったレビュー可能な状態に保つ
• プルリクエスト説明にコンテキストを提供する
• フィードバックに建設的に対応する

言語固有の適応

これらの原則は言語に依存しませんが、特定のプログラミング言語に適応させてください:

• 静的型付け: 利用可能な場合は強力な型を使用する
• 動的型付け: ランタイム検証を追加する
• OOP言語: SOLID原則を適用する
• 関数型言語: ピュア関数と不変性を優先する
• 並行処理: スレッド安全性の言語固有パターンに従う