こちらは、Mavs Advent Calendar2023の10日目の記事です！

🎄🎄🎄

こんにちは、タロウです。

Notion × Github Projectsを活用し、社内で行っているプロジェクトのレビュー文化を紹介したいと思います！

レビューというと・・「これは必要でしょうか？」「なぜですか？」「こういう書き方もできますよ」と攻撃的のような文章が見られたり、レビューイ（レビューしてもらう人・作成者）がコメントもらって判断に困るような文章があったりと、果たして効果的なレビューなのだろうか・・と考えることが多くあります。

また、十数年前に新卒で入社した老舗IT屋では

• コードを紙で印刷し赤ペンを入れてもらう
• SVNのログでレビュー
• 修正した差分ファイル（コード・Excel製の設計書）を抜き出しWinMergeで差分確認

などいろいろなやり方がありました。
その後に携わったプロジェクトでは、

• git diffでのコードレビュー
• 対面・回覧で設計書読み合わせ
• GitHubやBacklogなどのプラットフォーム機能を使用したレビュー

など会話とWebツールを使用する、よりスムーズに手間を少なく意思を伝えやすい方法に変わってきました。ただ、育ってきた・関わってきた環境によりレビューの構えかたが人ぞれぞれなので、人に任せてしまうと少し危険に感じる部分もあります。

どんな小さな修正でもコードレビューを行う

「issueを作成している時間の方が、時間がかかる」そう思った方たくさんいらっしゃる気がしています。私も何度も遭遇しました。たった1行、たった数文字修正するがためにissueに修正内容やキャプチャを貼るのがとても億劫になります。

億劫と感じるレベルが人によって違うため、修正の難易度・ボリュームにかかわらず1回許すとどんどんやらなくなります。

最初は文字修正だけ、ボタン押下時のパラメータだけ、表示順の入れ替え・・・などと徐々に億劫レベルが上がっていき、いづれ振り返ることのできないisssue無し修正が標準化します。

「仕組みで防ぐ」に行き着く

プロジェクト・コードの管理をGitHubで行っており、mainブランチ（最新の状態を保持しているブランチ）へマージするためにはレビューを必須としました。

どんな小さな修正でもPull requestを作成しないとマージできなくなります。
もちろんmainブランチへダイレクトに修正を入れることもできません。

簡単に反映できないような仕組みとしないと人間の怠惰を防ぐことはできなさそうです。
自分の怠けも含めて効果はとてもありました！

また毎度issueを作成し、Pull requestによるレビューを行うことでしっかり差分を確認できるようになりました。issueでは問題点を把握し、Pull requestでは解消内容とコード差分を見る流れが出来上がります。

issueは迷うことなく書ける

テンプレートを使用することで書くことへの迷いを少しでも少なくできます。

Pull requestではレビュアーに優しく

こちらもテンプレートを使用しています。あらかじめレビューを行うのに必要な内容を把握することができます。
人によって書き方が変わることがないため、抽象度や読み方の差をなくすことができました。レビュアーにとても優しくしています。

Notionでは回覧or読み合わせを行う

ドキュメント類はNotionを使用しています。マージなどを行うことができないので、更新した分は回覧や対面の読み合わせでレビューを行っています。

何か会話が発生するイベントで”ついでだから・・”と別のゴールが設定されている会話を混ぜていませんか？？それぞれのミーティングに目的とゴール設定を行うことでダラダラと続いて集中力がもたなくなります。

ついついやってしまいがちですが、朝会夕会などのミーティング・振り返りの際にに一緒に行うのではなく、目的が異なるミーティングの場合は仕切り直して開催した方が良いことが多くありました。

そんな読み合わせの場では順に読み上げていきますが、事前にわからないこと・気になったことなどストップしやすいジャブを打ちます。（メンバーそれぞれ見えている景色が違うため声を上げてもらえるのはとても貴重です）

レビュー例

定期的にリリース作業を行うための”リリース手順・内容”について例を紹介します。

開発してきたissueが完了しmainブランチへマージ後は、手動で本番環境へリリースを行っています。
本番環境へのリリースでは、

• メンテナンスモードへ切り替え
• 環境変数の変更
• データベースのテーブル・カラム変更
• データ検証

などと場合によってやることが多々あるため、まずはタイムスケジュールを共有しレビュー範囲の認識を合わせます。

手順や項目ごとに止めながら問題ないかを確認し、問題部分は訂正しながら進めます。

読み合わせが終わる頃にはいつどんなリリースが行われ、明確なissueの完成目処をチーム全員で認識を合わせることができました。

こちらで紹介したNotionを使用した設計書も同様に、読み合わせや回覧でレビューを行います。回覧での指摘事項がある場合はコメント機能を使用することで意思疎通に困ることなく明確に該当箇所を示すことができました。

情報共有・指摘・アドバイスを明確に

冒頭でも触れたレビューイが”判断に困るような文章”をいかに書かないか、気をつけたポイントをまとめたいと思います。

ちくちく言葉のレビューは何も産まない

ちくちく言葉については、こちらで少し詳しく書いたのでよければご覧ください！
コードレビューや設計書レビューで「〜〜と思うのですが？」「コーディングルールをしっかり読みましたか？」などというちくちくしたレビューコメントをしたことはないでしょうか？？

レビュアーが上司・リーダーであるケースの方が多いことがありますが、無意識に文脈に表現されてしまうことが多いと思います。より良くするため、不具合や今後の成長に繋げることより立場や優位性を保つための場になってしまうことを多く見てきた気がします。

プロジェクトではメンバーの観点をすり合わせた上で、年齢年数に関係なく相互でレビューを行うようにしました。（若いメンバーの観点を育成するためにも早いうちからチャレンジが望ましいと考えています）

また、レビューする側になることで、自分が同じコメント受け取ったらどうなのかを意識できるようになるため、物事の伝え方のトレーニングになります。

行動まで記載しよう

どうすれば良いかわからないコメントは、迷い、萎縮を生み、スムーズさを低下させることにつながります。コメントを入れた上でどうして欲しいか行動まで記載した方がスムーズでした。

• 〇〇ではなく〇〇が正しい値です。修正をお願いします！
• 〇〇値を使っている箇所は他にもあるので、検索して確認をお願いします！

などコメントを認識してもらった後にどういう行動をして欲しいのか書くようにしています！

さいごに

とあるプロジェクトで進めているレビュー文化について紹介でした。
基本的にはレビューなしで進めることできなく、自分以外の目が入り安全を確保できる仕組みで運用しています。

スピード感を失わないよう、効果は同じでも省略できることは省略したり、レビュアー（レビューする人）にあまり負担をかけないような工夫など、プロジェクトに合った方法を早い段階で見つけることが重要と感じました。
（もちろん納品時にレビューの成果物が必要になる場合は省略しません）

面倒くさいこと・怠惰は誰にでも起きえるので、仕組みで守らざるを得ない環境を作り運用していきましょう！