これまで少し大きめな機能であれば、コードを書く前にまず仕様や実装の方針をissueのdescriptionにまとめ、それを先にレビューしてもらってから実装にとりかかるということをしていた。最近、その方針をそもそもrepositoryのファイルとして書いて、PullRequestしてレビューしてもらうようにしたら便利だったのでご紹介。
なぜコードを書く前に仕様や実装の方針をレビューするのか
前提としてなぜコードを書く前に仕様や実装の方針をレビューして欲しいのかについて書いておく。これはとにかく手戻りの量を少なくしたいという要求のためである。
実装に取り掛かろうとすると、実装の方針はいくつか思いつくが、どれが一番よいか迷うことはよくある。その場合に誰にも相談せず自分だけで判断し、コードを書いてからPullRequestを送った場合、もしその選択に重大なミスがあった場合全て書きなおさないといけない。これは大きな手戻りが発生する。
このような手戻りを防ぐためには、まずは実装の方針をMarkdownか何かで書き、それを先にレビューしてもらうという手がある。例えば以下のようなフォーマットで書くなどが考えられる。
# 実装方針案1 ... ## メリット ## デメリット # 実装方針案2 ... ## メリット ## デメリット # 検討 案1は工数が非常に少なく済むが、案2のようにしないと今後技術的負債になりうる。 そこで多少大変だとしても、今回は案2の方針で行おうと思うがどうか。
このフォーマットは単なる例で、その他にもデータのスキーマなどを先に相談したり、処理の流れを日本語で書いてみたりでも良い。いろんな形式で書いて先にレビューしてもらうことで、その時点で筋が悪い部分は指摘され、手戻りの量が少なくなる。
これまではどうしていたか
これまではこのような実装方針レビューはGithubのissueのdescriptionに書いたり、issueのコメントに書いたりして、issueベースでレビューをしてもらっていた。この方法でも良いのだけど、次の課題があった。
- ある部分が筋が悪いという指摘を書くのに、いちいちその文章を引用してコメントしていて、面倒であった
- 指摘後、実際に修正してもらった時に、その修正点が分かりづらかった
- 新しく入った人に先に実装方針レビューやったほうが良いというアドバイスをしても、その例をissue検索で探して渡す必要があった
課題を解決するために試してみたこと
これらの課題を解決するために、実装方針レビュー用のディレクトリを作って、そこにMarkdownでファイルを作って、普通のPullRequestベースのレビューでコメントを書いてもらえば良いのでは？と考えた。これは以前別のチームでやっているという話も小耳に挟んでいたので、実際に試してみた。
次の流れで実装方針をレビューしてもらう。
- docs/spec_review/みたいなディレクトリを作っておく
- そのディレクトリ以下にYYYYmmdd-hoge-spec.mdのようなファイルを配置し、そこに方針を書いていく
- 完成したらいつもどおりPullRequestを送る
- そのファイルに対して、レビュワーにはラインコメントを書いてもらう
- レビューされたら、コメントに返信したり、方針のファイルを変更したりする
- レビューが通ったらmergeする
- あとはそのファイルを見ながら実装する
このようにすることで先ほど挙げた課題となっていることを解決できた。
- ある部分にコメントするのは普通にラインコメントで良い
- 方針案の修正内容がcommitになるためわかりやすい
- docs/spec_review/以下にどんどん実装方針レビューが溜まっていくため、後から入ってくる人に例として出しやすい
まとめ
今回は仕様や実装方針相談をPullRequestで行う取り組みについて書いてみた。ちょっと試してみただけだけど、思ったより良い雰囲気だったので、今後も続けていこうと思う。
