こんにちは。
ヒコーキ好きのみこやんです。
最近の私はドキュメント仕事が増えていまして、何かとNotionに規約やら規則やらを書き綴る時間が多くなりました。
そんな中、私が関わっているプロジェクトに、まだ明確に定められていない規約類があったので、その作成に着手。ようやく最近チーム内展開を終えたところとあいなりました。
今回は、コードレビュー規約を作る上で考えるべきことについて、かいつまんでお話してみたいと思います。
※運用編も併せてご覧ください。
コードレビューについて考察する
「コードレビュー規約」をつくる意義
コードレビューは、今ドキの開発チームであれば、どういうカタチであれ実施しているところが多いと思います。
そして、コードレビューについては、暗黙的もしくは惰性的に行っていることもあるかと思います。
もちろん、レビューア(レビューをする人)のスキルや経験などで、レビューの内容自体は変わってくるのですが、それ以前に「コードレビューとは何か」を明確に定めておかないと、ちょっとしたきっかけでチームが不協和音に包まれかねません。
「そんなオーバーな」と思われるかもしれませんが、開発者も人ですし、文字通り十人十色です。組織によっては契約社員やSESなど、外部のエンジニアを招くことも往々にしてありますから、外人部隊みたいな状態と言っても過言ではないでしょう。
そのように構成された開発チームにおいて、コードレビューを発端としたトラブルが生まれることは想像に難くなく、むしろ当然とも思えます。
たとえ仲の良いメンバーだけで揃ったチームであったとしても、テキストベースでのやりとりがメインのコードレビューにおいて、ちょっとした表現やニュアンスから生まれる誤解や意図せぬ解釈もあるでしょう。
こうした事態を回避…は難しいかもしれませんが、期待できる予防線として使用するための「コーディング規約」を、簡潔に整えておく必要があります。
コードレビューで重要なこととは？
コードレビュー規約を作成するにあたり、まずは「コードレビューとは何か？」を考えてみました。
イマサラすぎるかもしれませんが、改めて考察し、整理しておきます。
ここで「コードベース」とは、その開発チームが関与する1つのプロダクトの包括的なソースコードを指します。
- コードベースの品質を保ち、一貫性を維持する行為
- その結果、コードベース保守の容易性を確保する行為
これは、コードレビュー規約を制定する目的そのものと言えそうです。
次に、「コードレビューにおいて重要なことは何か？」を考えてみました。
前節で書いたとおり、コードレビューを実施する中でチームの「不協和音」が生まれてしまわないように、本来の目的が遂行できるようにしなければならない、と言えると思います。
ここで「レビューア」とはコードレビューをする人、「レビューイ」とはコードレビューを受ける人を指します。
- レビューア、レビューイの双方が、客観性と論理性を持ち続けること
- レビューア、レビューイの双方は、両者の結論が一致し合意できるまでコードレビューを継続すること
客観性と論理性が不可欠なことは、改めて言うまでもないとは思われがちです。
しかし、コードレビューのど真ん中に入っていくと、自分の指摘が受け入れられない、あるいは自分のコードが受け入れられない、といった感情が徐々に湧いてきてしまうことがあります。
感情から押し出されたやりとりは、コードレビューであろうがなかろうが、決して良い結果を生まないことは、我々は経験的に知っているはずです。
ですが、前節で書いた通り、さまざまなタイプの人で構成された開発チームのメンバー全員が、必ずしも冷静なままいられるとは限りません。
したがって、分かっていてもあえて明記しておかなければならないものと言えるでしょう。
次の一文は意外な印象を受けるかもしれません。
これも「感情的なコードレビューをしてはならない」の中の肝の1つとも言えます。
感情に流されたレビューア、もしくはレビューイは、相手の指摘に対して、さまざまな感情的理由によって合意を拒んだり、頭では分かっていたとしても納得できなかったりすることがあるでしょう。
そうした場面では、指摘を無視してコードレビューを放棄したり、意図的に中断させて不必要にコードレビューを長引かせたりするようなタイプの人も現れます。これはもはや、怒りにも似た状態になってしまっているとも言え、不健全レベルMAXとも言えるでしょう。
ふてくされるタイプの場合、自分の指摘を途中で撤回して、納得の有無に関わらず相手の指摘を丸ごと受け入れてレビューを完了させてしまう人もいます。
こうした状況を生み出さないためのルールを制定する必要があります。
コードレビュー規約の中身を考える
読める分量の、簡単な文章で構成しよう
以上のことを踏まえて、実に簡単な規約を制定してみました。
1.目的
コードレビューの実践は、以下を目的として行うものである。
- コードベースの品質を保ち、一貫性を維持する。
- その結果、コードベース保守の容易性を確保する。
2.用語
以下に、本規約にて使用する用語を定義する。
レビュー／コードレビュー ： コーディング規約に基づいて、コードに関する議論や評価を行うこと。
レビューア（レビュアー） ： レビューする人。
レビューイ（レビュイー） ： レビューを受ける人。レビューイは、レビューアにレビューを依頼することで、レビューが開始される。3.遵守事項
- レビューでは、コード可読性や、コードの一貫性（個人技のようなコーディングスタイルではないこと）など、コーディング規約に基づく評価を行うこと。
- すべてのレビューにおいて、レビューアとレビューイは対等であり、常にコーディング規約と照らし合わせた上で、対象となるコードに向き合い議論を交わすこと。また、その議論は双方ともに客観的かつ論理的であること（感情・直感的な議論は避けること）。
- レビューアは、対象となるコードについて議論する際、可能な限りサンプルコードや疑似コード、有効な文献などを用いて評価すること。
- 良いコードには
LGTM等にて評価するのが望ましい。4.禁止事項
- レビューアは、対象となるコードに対して感情的な評価をコメントしてはならない。
- レビューイは、レビューアの指摘に対して感情的な反論をコメントしてはならい。
- レビューアは、レビューイの説明を無視したり、合意のない状態でレビューを中断・放棄してはならない。
- レビューイは、レビューアの指摘に対して、無視・中断・放置・放棄をしてはならない。
「目的」には、前節の最初に書いた文章を、ほぼそのまま持ってきています。
「用語」欄は案外重要で、この定義によって、書いている内容の表記ゆれを防ぎつつ、読み手全員に同じ意味を伝えることが可能になります。
「遵守事項」には、コードレビューで絶対遵守すべき事柄を手短にまとめました。4行程度であれば、なんとか皆が読んでくれるでしょう。
「禁止事項」には、コードレビューで絶対やってはいけない事柄を手短にまとめました。冷静なときに読めば、普通に理解できることだと思います。しかし前節でも書いた通り、コードレビューのど真ん中で感情の渦に飲まれてしまった人にとって、ここに書かれたことはある意味「失われた知性」とも言えるでしょう。
なお、この規約は、弊社のLetro開発チーム全体に適用し、現在も運用中のコードレビュー規約となっています。
実はさらにこの後ろに、コードレビューにおける評価基準を設けていますが、これは組織、プロダクト、チームなどで異なると思いますので、本記事では長くなってしまうこともあり、割愛いたします。
運用できるサイズの、有意な規約を作ろう
「仏作って魂入れず」ではありませんが、規約や規則というのは、往々にして「規約作って運用されず」という状態に至ることがあります。
この原因の1つとしては、規約にすべてを詰め込んだ結果、誰にも読まれず、読まれても記憶されず、必要な場面でも長すぎるため参照する気持ちが失われる、といったことがあると考えています。
ですので、私は以下の3点を、規約を作る際には十分に心がけるようにしています。
- 絶対に必要なことだけ入れる(取捨選択)
- 可能な限り理解しやすい言葉を選ぶ(ただし規約という書類の性質上、難しい場合もある)
- 誰が読んでも誤解されにくい文章を構成する
実は弊社はベトナムにも開発パートナーが多数在籍しています。そのため、上記の2.については「翻訳しやすい＆誤訳されにくい日本語で作成する」という意図も含まれています。
規約の作成を進めていくと、実際にはこの3点をすべて満たした文面の作成はかなり難しいと思います。
ですので、一度ラフ案を作ったらチームメンバー(一部のメンバーでもよい)とミーティングを設定して、意見交換をしながら最終稿まで持っていくことをオススメします。
以上、コードレビュー規約を制定する上での考慮点とともに、弊社Letro開発チームで実際に使用している規約の一部を抜粋しながら、ご紹介しました。
次回は、このコードレビュー規約の運用面について文書化したものがご紹介できればと思います。
最後までお読みいただき、ありがとうございました。
プログラミングもサーバもフロント(チョトだけ)もインフラ(オンプレ中心)もwebもゲームも組み込みも幅広く何でも雑多にやってきた古株ですが、フルスタックではありません。好きなものはプログラミングと計算機科学。我々と一緒に好きなプログラミングを楽しみませんか？
