web-dev-qa-db-ja.com

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

前提条件

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

ワークフロー

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

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

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

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

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

IDEサポート

私は知っている、カスタムコメントタグはEclipseとnetbeansで可能です。もちろん、blablaStormファミリーにも含まれているはずです。

Example of custom filtered task-from-comments in Eclipse

ご質問

  1. この方法論は実行可能だと思いますか？
  2. あなたは似たようなことを知っていますか？
  3. その中で何を改善できますか？
teamworkcode-reviewsworkflowsdvcs
16
gaRex

アイデアは実際には非常にいいです。一般的なワークフローとは異なり、このワークフローを使用するにはレビューをコードに直接保存するため、技術的にはテキストエディター以外は必要ありません。 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」をキーワードとして選択しないでください。醜く聞こえます。 ;）

14
Arseni Mourzenko

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

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

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

4
Kate Gregory

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

2
Adam Hupp