📚

Toriida 式業務向けコードレビュー作業フロー

2025/02/03に公開

あくまで筆者にとって効率が良い作業フローです。

アプリケーションのソースコードを想定しています。

疑似コードによる表現

if (一目で意図も差分も把握できる小さなプルリクエストである) {
    プルリクエスト上で確認する;
    exit;
}

if (ローカル環境がない) {
    ローカル環境を構築する;
}

ソースブランチをチェックアウトする;

IDE でリポジトリを開く;

チェックすべき宣言のリスト := (差分に含まれる宣言のリスト + 差分を含む宣言のリスト);

for (宣言 in チェックすべき宣言のリスト) {

    if (宣言またはその内容が、リポジトリのコーディング規約に抵触している) {
        プルリクエスト上で修正を依頼する;
    }

    if (宣言またはその内容に、コーディング面で意図が不明な部分がある) {
        プルリクエスト上で質問する;

        if (必要な差分である and 新規参画者が戸惑いそう) {
            コードコメントの追加を依頼する;
        }
    }

    if (宣言の内容に、要件に照らして意図が不明な部分がある) {
        プルリクエスト上で質問する;

        if (必要な差分である and 新規参画者が戸惑いそう) {
            コードコメントの追加を依頼する;
        }
    }
}

解説

IDE で開いて確認する理由

シンタックスハイライト・APIドキュメントの表示・静的解析・宣言箇所への移動などの IDE の支援を受けつつコードレビューする方が、そうしないよりも質・スピードともに向上するからです。

それなりの性能をもつ PC を業務で使っていれば IDE で開く程度の時間はたいしたものでないですし、そうでないのであれば購入の理由やコーヒーを淹れる時間にすると良いでしょう。

コーディング規約について

業務で参画するメンバーには様々なバックグラウンドがあり、そしてメンバーは業務指示で参画しています。メンバー間で「良い」と考えるソースコードや、どの程度「良い」ソースコードを提出すべきかについて、大きな認識の差があることも珍しくありません。

そこで「このリポジトリではこうする」という方針としてコーディング規約を整備することで、コーディングする側とコードレビューする側双方の迷いや繰り返しの議論を減らすことができ、質とスピードの底上げが図れます。

媒体には README.md 以外のマークダウンファイルか、過去のリビジョンを確認できる wiki が使いやすいと感じます。

最初の内容は以下の2点程度の少ないものでも良いでしょう。

  • フォーマットツールの指定、およびその使用の義務付け
  • 基礎となる命名規則 (camelCase, PascalCase, snake_case, kebab-case)

「新規参画者が戸惑いそう」という基準

勘に頼る部分が大きいですが、それでも大切な基準だと考えています。

「新規参画者」とは書いていますが、実際には未来の自分自身であったことも少なくありません。しばらく経って保守や改修が必要になってから、意図が不明瞭なコードを調査するのはかなり厳しいです。

逆にコーディングする際には、新規参画者が戸惑いそうなコードをなるべく少なくし、どうしても必要な場合にはコードコメントを残すことをお勧めします。そうすることでレビュアーの負荷も軽減され、プルリクエストをクローズするまでの時間を短縮することが狙えます。

もしよりシステマチックにこれらが行える基準を持っている方は、ぜひ教えていただけると嬉しいです。

Discussion