コードコメントのみを使用するコードレビューは良いアイデアですか？

前提条件

• チームはDVCSを使用します
• IDEはコメントの解析をサポートしています（TODOなど）
• CodeCollaboratorのようなツールは予算的に高価です
• gerritのようなツールはインストールするには複雑すぎるか、使用できません

ワークフロー

• 著者は中央リポジトリ機能ブランチのどこかに公開しています
• レビュー担当者が取得してレビューを開始します

• 質問/問題レビューアの場合、「REV」などの特別なラベルを付けてコメントを作成します。そのようなラベルは、製品コードに含めることはできません-レビュー段階でのみ：

  $somevar = 123;
  // REV Why do echo this here?
  echo $somevar;
  

• レビュアーがコメントの投稿を完了すると、愚かなメッセージ「comments」でコミットし、プッシュバックします

• 作成者は機能ブランチをプルバックし、同様の方法でコメントに回答するか、コードを改善してプッシュバックします
• 「REV」コメントがなくなると、そのレビューは正常に終了したと考えることができます。
• 作成者は機能ブランチをインタラクティブにリベースし、それを押しつぶしてそれらの「コメント」コミットを削除します。これで機能をマージして、通常は内部レビューが正常に完了した後のアクションを開発または実行する準備ができました

IDEサポート

私は、カスタムのコメントタグがEclipseとNetBeansで可能であることを知っています。確かにそれはblablaStormファミリーにもあるはずです。

ご質問

1. この方法論は実行可能であると思いますか？
2. 同様のことを知っていますか？
3. それで何を改善できますか？

アイデアは実際にはとてもいいです。一般的なワークフローとは異なり、レビューをコードに直接保存するため、技術的には、このワークフローを使用するためにテキストエディター以外は必要ありません。IDEのサポート、特に下部にレビューのリストを表示する機能も優れています。

まだいくつかの欠点があります。

• 非常に小さなチームでは問題なく機能しますが、大規模なチームでは、何がいつ、誰が、どの結果でレビューされたかを追跡する必要があります。実際にこの種の追跡を行っていますが（バージョン管理ですべてを把握できます）、使用と検索は非常に難しく、多くの場合、改訂版を手動または半手動で検索する必要があります。

• レビュアーがレビューされたポイントが実際にどのように適用されたかを知るためにレビュアーからの十分なフィードバックを持っているとは思いません。

  次の状況を想像してください。アリスはエリックのコードを初めてレビューしています。彼女は、若い開発者であるエリックが、実際に使用されているプログラミング言語で最も記述的ではない構文を使用していることに気付きました。

  アリスは代替構文を提案し、コードをエリックに送り返します。彼は、正しく理解していると信じるこの代替構文を使用してコードを書き直し、対応する// BLAコメントを削除します。

  翌週、彼女は2回目のレビュー用のコードを受け取ります。彼女は、エリックがそれをどのように解決したかを見るために、彼女が最初のレビュー中にこの発言をしたことを実際に思い出すことができますか？

  より正式なレビュープロセスでは、アリスは発言したことをすぐに確認し、関連するコードの差分を確認して、エリックが自分に言った構文を誤解したことに気付きました。

• 人はまだ人です。これらのコメントの一部は本番コードになり、一部は完全に古くなったままゴミとして残ると確信しています。

  もちろん、他のコメントにも同じ問題が存在します。たとえば、実稼働環境には多数のTODOコメント（最も有用なものを含む：「TODO：以下のコードにコメントを付けてください。」）、および対応するコードが更新されたときに更新されなかったコメントが多数あります。

  たとえば、コードの元の作成者またはレビュアーが去っても、新しい開発者はレビューの内容を理解できないため、コメントは永遠に残り、誰かがそれを一掃するか、実際に何を理解するかを勇気づけるのを待ちますそれは言います。

• これは、対面レビューに置き換わるものではありません（ただし、対面で行われない他のより正式なレビューにも同じ問題が当てはまります）。

  特に、元のレビューに説明が必要な場合、レビュー担当者とレビュー対象者はある種の議論を開始します。大きなBLAコメントが見つかるだけでなく、それらの議論はバージョン管理のログを汚染することにもなります。

• また、構文（TODOコメントにも存在する）で軽微な問題が発生する場合があります。たとえば、長い「// BLA」コメントが複数の行に表示され、誰かがこのように書くことに決めた場合はどうなりますか。

  // BLA This is a very long comment which is way beyond 80 characters, so it actually
  // fills more then one line. Since the next lines start with slashes, but not "BLA"
  // keyword, the IDE may not be able to show those lines, and display only the first one.
  

• 最後に、マイナーで非常に個人的なメモとして：キーワードとして「BLA」を選択しないでください。soundsいですね。;）

コード内のコメントをコンパニオンドキュメントで補完します。これは調査結果を要約し、コメントが削除された後も存続します。これの利点は次のとおりです。

• コンパクト。渡されたポインターがnullでないこと（または使用している言語の他の一般的な初心者エラー）を定期的に確認できない場合、レビュアーはその旨のREVコメントを数十個残して、ドキュメントに「それらをすべてリストせずに、ポインターが最初にチェックされなかった37の場所を見つけました
• 賞賛のための場所。REV this is a nice designちょっと変わったように思えるコメントもありますが、コードレビューには承認と修正が含まれていることがよくあります
• インタラクティブ。サンプルコメントは「なぜこれをしたのですか？」です。それは非常に典型的なものです。コメントのみのアプローチは会話をサポートしていません。ユーザーはコードを変更してコメントを削除したり、コメントを削除したりできます。しかし、「なぜこれをしたのですか？」「これを変えてください、それは間違っています」は同じものではありません。
• 記録を残します。後のレビュー担当者は、コードが実際に変更されたかどうか、またはコメントが削除されただけかどうかを確認できます。また、コメントが「オンボード」であり、開発者がその後のレビューで同じ間違いをしていないことも確認できます。

また、レビューを行い、レビューに応答するためにワークアイテムを使用し、チェックインをそれに関連付けます。これにより、古いチェンジセットでコメントを見つけやすくなり、各コメントが別のチェンジセットでどのように処理されたかを確認できます。

他の人は、このアプローチの制限について話しました。gerritのようなツールをインストールするのは難しいと言いましたが、phabricator（http://www.phabricator.com）をご覧になることをお勧めします。これはFacebookが長年使用してきたコードレビューシステムであり、最近オープンソース化されました。インストールは難しくなく、優れたワークフローを備えており、他のコメントで言及されているすべての問題を解決します。