文書やコードのレビューで気をつけていること

文書やコードにはレビューというプロセスがあります。書いた人ではない人がそれらを読んで意見を述べて、意見を反映させてよりよいものを作っていくプロセスです。明にレビューという名前がついていなくても人の作品に意見を求められることが多いと思います。

このレビューというやつは、やることだけ見れば簡単そうに見えるのですが、非常に考えておくとよいことが多いです。本記事ではレビューはこうするといいものになるんじゃないかなと私が思って実践していることを共有します。なにか響くところがあれば参考にしてもらえたらなという程度の話です。

レビューアとして、まずは段階に応じた粒度を心がけています。レビュー対象のソースや文書は、最初は粗い物を出して、どんどん練り上げて、最終的に完成に持ち込むものです。したがって「とりあえず書きなぐってみた」という段階で細かい指摘をしてもあまり意味がありません。そういう指摘をしても次のレビューのときに指摘した部分がまるごとなくなっている場合があるからです。ここの塩梅は非常に難しいのですが、たとえば文書でいうとわたしは初期のレビューでは全体構成などについては話しますが、「てにをは」レベルの指摘は、よほど意味が通じないという場合を除き、やりません。

指摘の重要さの切り分けも重要です。わたしは修正したほうがはっきりよいと言える場合は指摘をためらいませんが、好みの問題のときはそもそも指摘すらしません。自分でもどっちでもいいと思っていることでお互いの時間を使うのはもったいないからです。とくに、ここで変にこだわるとレビューに対して寄与しない激論がかわされて、なにかやってるように見えて何も進んでいないという悲しいことになります。レビューの目的は相手を論破することではなく、より良いものを作ることです。

レビューをする側ではなく、依頼する側としてもやっておくべきことがあります。まずは対象読者の明確化が必要です*1。たとえば、初心者向けの文書では手厚く説明しているように見える文書であっても、その道のプロ向けのものだと当たり前のことをクドクド書いているだけという見方ができます。ここを最初に決めておかず、意識が共有されていないとレビューが迷走しがちです。

続いて、どういう人にはどういう観点で見てほしいかも書きます。たとえば初心者用の文書では、プロには技術的に合っているかどうかを重点的に見てもらい、対象読者の人にはこの文書で自分が理解できたかを見てもらう、などです。事前にレビュー観点を共有できているとお互いに手間が減らせると考えています。とくにレビューに慣れていない人にレビューアを依頼すると効果的かと思います。

いろいろ書いてきましたが、やっぱりレビューは難しいですね。ここに書かなかったこともたくさんあるのですが、レビュー対象物の性質によって適切なやりかたが大きく変わりそうなものは紹介を避けました。

みなさんも気をつけていることがあれば教えて下さい。おわり。

*1:これはレビュー有無に関係なくすべての文書に対してあるべきだと思ってます