ログイン

E-Learning

UCL社内教育用ブログ

コーディングルールの詳細

執筆者:

竇 亮

カテゴリ:

1. 命名規則・ファイル構成・コメントの書き方

1-1. 命名規則

  1. 変数・メソッド・クラス命名の統一
    • 変数
      • キャメルケース（userName, totalCount など）を採用
      • 定数はすべて大文字 + アンダースコア（MAX_SIZE, DEFAULT_COLOR など）
    • メソッド
      • 動詞から始める（getUserName(), calculateTotal() など）
      • アクションを明確に示すことで可読性が向上
    • クラス/インターフェース
      • パスカルケース（UserController, PaymentService など）
      • インターフェース名には I を付けるか否かはチームルールで統一（例：IUserRepository）
  2. 名前の長さと意味のバランス
    • 短すぎる（x, y）と意味が不明瞭
    • 長すぎる（getTheTotalNumberOfAllUsersInTheSystem）と可読性が低下
    • 適度に短く、しかし役割が分かる名前を心がける

1-2. ファイル構成

  1. ディレクトリ構造
    • 機能ごと、ドメインごとなど、チームの開発スタイルに合わせて階層を決定
    • 例：src/ controllers/ services/ repositories/ models/ utils/
    • 単一ファイルの肥大化を避け、責務ごとに分割する
  2. ファイル命名
    • クラス名と同じファイル名にする（JavaやC#など、クラス名 = ファイル名が基本）
    • 複数クラスを1ファイルにまとめない（保守性を高めるため）

1-3. コメントの書き方

  1. ドキュメンテーションコメントの基本
    • メソッドやクラスの冒頭に、役割やパラメータ、戻り値などを明記
    • JavaDocやDocstring形式など、言語やフレームワークの標準に合わせる
  2. 実装意図の説明
    • 「なぜこの実装にしたのか」「どのようなアルゴリズムか」を簡潔に書く
    • 単なるソースコードの説明ではなく、開発者の思考を伝えると保守性が上がる
  3. コメントの更新
    • コード修正時にコメントも必ず更新する
    • 古いコメントは誤解を生むため、定期的に見直す

2. 静的解析ツールとの連携

2-1. Lintツールやフォーマッタの活用

  1. Lintツール
    • 例：ESLint（JavaScript）、Checkstyle（Java）、Pylint（Python）など
    • コードの書式や潜在的なバグを自動検出し、警告やエラーを表示
    • チームでルールファイル（.eslintrc, checkstyle.xmlなど）を共有し、統一的なチェックを実施
  2. フォーマッタ
    • 例：Prettier（JavaScript, TypeScript）, Black（Python）, clang-format（C++）など
    • インデントや改行位置、スペースの入れ方などを自動整形
    • 手動調整の手間を省き、スタイルに関する議論を削減

2-2. CI/CDとの統合

  1. ビルドパイプラインでのLint/Formatチェック
    • コードがプッシュされたら、自動的にLintを走らせ、エラーがあればビルド失敗にする
    • コード整形ツールをCI段階で実行し、開発者がPull Request前に整形を行う運用を徹底
  2. レポートの可視化
    • Lint結果やフォーマット状況をCI/CDツールのレポートで確認
    • 警告数やエラー数をグラフ化し、継続的に改善を図る

2-3. メリットと注意点

  1. メリット
    • 開発者がルールを守るための負担が軽減
    • コードレビュー時にスタイルの議論が減り、ロジックに集中できる
    • 潜在バグや警告を早期に検知し、品質を高める
  2. 注意点
    • 過度に厳しいルールは開発者のフラストレーションになる場合がある
    • ルールの導入・変更時にはチーム合意を得て、徐々に適用範囲を広げる

3. 運用・定着のためのポイント

  1. チーム合意とドキュメント整備
    • コーディングルールをWikiやREADMEに明記し、いつでも参照できるようにする
    • 重要なルール（命名規則、フォーマット、ディレクトリ構成など）を優先して合意形成
  2. 自動チェックの徹底
    • Lintやフォーマットをコミット前フック（Git Hooks）やCIで強制し、守られないとビルドが通らない仕組みにする
    • 開発者が手動で整形・修正する場合も、コマンドひとつで簡単に対応できるようにする
  3. 定期的な見直し
    • プロジェクトの規模や技術スタックが変われば、コーディングルールもアップデートする必要がある
    • 定期的にチームでレビューし、現状に合わないルールは改訂・廃止

4. まとめ

  • 命名規則・ファイル構成・コメントの書き方
    • 可読性・保守性を大幅に向上させるため、統一したルールが重要
    • クラス/メソッド/変数命名の一貫性やドキュメンテーションコメントを活用する
  • 静的解析ツールとの連携
    • Lintやフォーマッタでコードスタイルを自動チェックし、ミスや警告を早期に発見
    • CI/CDパイプラインに組み込み、チーム全体でルールを守りやすい環境を整備
  • 運用・定着のためのポイント
    • ルールをチームで合意し、ドキュメント化
    • 自動化によるルール徹底、定期的な見直しを行い、継続的に品質を高める

コメント

コメントを残す

投稿をさらに読み込む