Zenn
📌

Sportip開発ガイドラインの紹介

2025/03/10に公開
Git
Test
開発
コードレビュー
ガイドライン
tech

はじめに

はじめまして。Sportipのテックリード、砂原です。
Zennで技術ブログを開始するにあたり、第一回では、開発規約のうち言語やフレームワークに依存しない部分に焦点を当ててご紹介いたします。

プルリクエスト（PR）

プルリクエスト運用の基本方針は、以下の内容となります。

1. 差分・コミット管理

  • 差分の最小化
    PRの変更差分が極力小さくなるよう努める。
  • 細かいPRの作成
    • 可能な限り小さな単位でPRを作成する。
    • 1つのPRに複数のコミットが含まれる場合、分割の可能性を検討する。
  • コミット単位のテスト
    各コミットが個別にテストをパスし、正しく動作する状態であることを確認する。
  • コミット整理
    レビュー依頼前に履歴を整理し、CI用フォーマッターによる自動変更など、本質的でない変更はsquashする。

2. ブランチ運用とPR管理

  • リファクタリングと機能追加／修正の分離
    リファクタリング専用ブランチを作成し、そのブランチから派生したブランチで機能追加や修正を行い、別々のPRとして提出する。
  • Draft PRの活用
    レビュー可能な状態になるまでDraft PRとして作成する。
  • ユニットテストの追加
    変更には必ず適切なユニットテストを付与する。
  • rebaseの実施
    master/mainとの差分が大きい場合は、mergeではなくrebaseを実施する。
  • マージ方法
    PRのマージは原則としてSquash Mergingを採用する。
  • PR説明のテンプレート
    基本のテンプレートを利用し、必要に応じて各リポジトリごとにカスタマイズ可能とする。
  • 不要なPRのクローズ
    スケジュール変更などにより、即時マージの予定がなくなったPRは適宜closeする。

3. 積極的なレビュー

  • 他のメンバーのPRにも目を通し、積極的にレビューを実施する。

コードレビュー

コードレビューは、以下の基本原則および各関係者の役割に基づいて行う。

1. 基本原則

  • レビュー対象の選定
    コードフォーマットは自動ツールに任せ、レビュー対象から除外する。
  • コミュニケーション
    丁寧な言葉遣いと建設的な議論を心がけ、必要に応じてミーティング等で同期的な議論を行う。

2. レビュー観点

品質

  • 仕様が正しく満たされているか。
  • コーディングルールが遵守されているか。
  • データ構造やアルゴリズムの選定が適切か。
  • 環境依存になっていないか。
  • 既存コードとの一貫性があるか。

セキュリティ

  • 秘密情報が混入していないか。
  • 入力の検証やサニタイズが適切に行われているか。
  • ベストプラクティスに沿った実装（例：パスワードのハッシュ化）がなされているか。

パフォーマンス

  • 計算量（時間・空間）が合理的か。
  • スケーラビリティが確保されているか。

3. レビュアーの役割

  • 依頼があれば迅速にコメントする。
  • 成果物のみを対象とし、個人の人格や態度に関する批判は行わない。
  • 大きな変更がある場合は、レビュイーに分割を依頼する。
  • 指摘の重要度（must、nit、fyiなど）を明確にする。
  • 問題点に対する改善策や対応案を提示する。
  • PRクローズに向けた道筋を示し、良い点についても積極的にコメントする。
  • コード改善の提案があれば、完璧でなくても承認する。
  • 参考文献（例：『リーダブルコード』）があれば、明記する。

4. レビュイーの役割

  • PRルールを遵守し、完成前にレビュアーとコミュニケーションを取る。
  • 実装前に、実装方針（修正内容、影響範囲など）を相談する。
  • 期限がある場合は、事前にレビューを依頼する旨伝えて時間を確保できるようにする。
  • レビュー依頼前に「コードレビュー事例集」を参照し、セルフチェックを実施する。
  • 必要な情報（設計背景、検討過程、重点箇所など）を記載する。
  • 修正完了後は随時、再レビューを依頼する。
  • 不明点があれば積極的に質問し、フィードバックを受け取る。

5. CodeRabbit

  • PRの状態は、以下の3パターンに分類する:
    1. [WIP]付きDraft: coderabbitおよび人間双方のレビュー対象外。
    2. [WIP]なしDraft: coderabbitはレビューを実施し、人間は対象外。
    3. Ready for review: 人間がレビュー対象となる。
  • [WIP]を外した直後は自動実行されないため、@coderabbitai full review とコメントして手動実行する。
  • rate limitに達した場合は、待機後に自動再実行されるので、そのままで問題ない。
  • CodeRabbitのレビューが不適切な場合は、適切に反論し、人間のレビュアーへの参考情報として提示する。
  • 必要に応じ、最初から[WIP]なしのPRとして作成してもよい。

コーディングルール

言語やフレームワークに依存しない共通のコーディングルールは、以下の通りとする。

1. 共通原則

  • DRY: Don’t Repeat Yourself
  • KISS: Keep It Simple, Stupid
  • YAGNI: You Ain’t Gonna Need It
  • Premature Optimization is the Root of All Evil
  • Don't guess, measure

2. フォーマット

  • GitHub Actionsを活用し、共通ルールの自動チェックを実施する。
  • インデントはスペース2つを採用する。

3. コメント

  • コメントは必要最小限に留め、説明的な変数名や関数名を使用する。
  • コード内のコメントは英語で記述する。
  • コメントには以下の内容を含める:
    • 設計背景および採用理由
    • アルゴリズムのリファレンス
    • 入力前提条件および例外時の挙動
    • ルール違反の合理的な理由（該当する場合）
  • スコープは最小限に、mutableよりimmutableな設計を選択する。
  • インターフェースの命名や引数の切り分けは、初見で誤解が生じないよう工夫する。
  • プラットフォーム固有のAPIは直接使用せず、安全な抽象レイヤー（例：Linuxのpthreadの代わりに、C++のstd::threadやPythonのthreading）を利用する。
  • OSSはライセンスに則り適切に利用し、パッケージマネージャ等でライセンス記載が求められる場合は、オープンソースライセンスを記載せず、クローズドソースであることを明示する。

テスト

テストに関する基本方針は、以下の通りとする。

1. ブラックボックステスト

  • 外部仕様のみを対象にテストを実施する。

2. ホワイトボックステスト

  • 以下の場合に限り実施する:
    • 将来変更される可能性が低い普遍的な実装。
    • 重要なアルゴリズムの中心部分。

3. ユニットテスト

  • 外部リソース（例：AWS）に依存せず、単独でテスト可能な設計を行う。
  • ユニットテスト、結合テスト、E2Eテストを適宜使い分け、テストカバレッジに一律の基準は設けない.

まとめ

Sportipの開発チームは、合理的な開発を実現するために日々改善を行っています。
また、当チームでは採用の拡大も目指しているので、内容にご興味をお持ちいただけましたら、ぜひお気軽に下記の採用フォームよりご連絡ください。

採用情報はこちら

Discussion