코드 주석 만 사용하는 코드 검토가 좋은 생각입니까?

전제 조건

• 팀은 DVCS를 사용합니다
• IDE는 주석 구문 분석 (TODO 등)을 지원합니다.
• CodeCollaborator와 같은 도구는 예산이 비싸다
• gerrit와 같은 도구는 설치하기에 너무 복잡하거나 사용할 수 없습니다

워크 플로우

• 저자는 중앙 저장소 기능 지점 어딘가에 게시
• 검토자가 가져 와서 검토 시작

• 일부 질문 / 문제 검토 자의 경우 "REV"와 같은 특수 레이블이있는 주석을 작성하십시오. 이러한 라벨은 프로덕션 코드에 포함되어서는 안되며 검토 단계에만 있어야합니다.

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

• 리뷰어가 댓글을 올리면 바보 같은 메시지 "댓글"로 커밋하고 다시 푸시합니다.

• 작성자는 기능 분기를 다시 가져와 유사한 방식으로 주석에 응답하거나 코드를 개선하고 다시 푸시합니다.
• "REV"의견이 사라지면 검토가 성공적으로 완료된 것입니다.
• 작성자는 대화식으로 기능 분기를 리베이스하고, 해당 "설명"커밋을 제거하기 위해 기능 분기를 축소하고 이제 내부 검토에 성공한 후 일반적으로 수행 할 수있는 조치를 개발하거나 수행하기 위해 기능을 병합 할 준비가되었습니다.

IDE 지원

이클립스 및 넷빈에서 사용자 정의 주석 태그가 가능하다는 것을 알고 있습니다. 물론 blablaStorm 제품군에도 있어야합니다.

질문

1. 이 방법론이 실행 가능하다고 생각하십니까?
2. 비슷한 것을 알고 있습니까?
3. 무엇을 개선 할 수 있습니까?

아이디어는 실제로 매우 좋습니다. 일반적인 워크 플로와는 달리 코드에서 직접 검토를 유지하므로 기술적 으로이 워크 플로를 사용하기 위해 텍스트 편집기 가 필요하지 않습니다 . IDE의 지원, 특히 리뷰 목록을 맨 아래에 표시하는 기능도 훌륭합니다.

여전히 몇 가지 단점이 있습니다.

• 아주 작은 팀에서는 잘 작동하지만 큰 팀에서는 검토 대상,시기, 대상 및 결과를 추적해야합니다 . 실제로 이러한 종류의 추적 (버전 제어를 통해 모든 것을 알 수 있음)이 있지만 사용 및 검색이 매우 어려우며 종종 수정을 통해 수동 또는 반 수동 검색이 필요합니다.

• 나는 검토자가 검토 된 포인트가 실제로 어떻게 적용되었는지 알기 위해 검토 자로부터 충분한 피드백을 받았다고 믿지 않습니다 .

  다음 상황을 상상해보십시오. Alice는 처음으로 Eric의 코드를 검토하고 있습니다. 그녀는 젊은 개발자 인 Eric이 실제로 사용 된 프로그래밍 언어에서 가장 설명이 어려운 구문을 사용했음을 알았습니다.

  Alice는 대체 구문을 제안하고 코드를 Eric에 다시 제출합니다. 그는 자신이 올바르게 이해한다고 생각하는이 대체 구문을 사용하여 코드를 다시 작성하고 해당 // BLA주석을 제거합니다 .

  다음 주에 두 번째 검토를위한 코드를받습니다. 에릭이 어떻게 해결했는지보기 위해 첫 번째 검토에서이 발언을했다는 것을 실제로 기억할 수 있습니까?

  보다 공식적인 검토 과정에서 Alice는 즉시 Eric이 자신이 말한 구문을 잘못 이해했음을 확인하기 위해 자신이 언급 한 내용을 확인하고 관련 코드의 차이점을 확인할 수있었습니다.

• 사람들은 여전히 ​​사람들입니다. 나는 그 의견 중 일부가 생산 코드로 끝나고 일부는 완전히 구식이면서 쓰레기로 남아있을 것이라고 확신 합니다.

  물론 다른 의견에도 같은 문제가 있습니다. 예를 들어, 프로덕션에는 많은 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"를 키워드로 선택하지 마십시오. 못 생겼어요 ;)

코드의 주석을 동반자 문서로 보완합니다. 이것은 결과를 요약하고 주석이 제거 된 후에 계속 진행됩니다. 이것의 장점은 다음과 같습니다.

• 소형. 사용자가 전달 된 포인터가 널 (null)이 아닌지 (또는 사용중인 언어의 다른 일반적인 초보자 오류) 아닌지 정기적으로 확인하지 못하면 검토자는 그 결과에 수십 개의 REV 주석을 남길 수 있으며 문서에서 " 포인터를 먼저 확인하지 않은 37 개의 장소를 찾았습니다. "
• 칭찬의 장소. 같은 의견 REV this is a nice design은 이상하게 보이지만 내 코드 검토에는 종종 승인뿐만 아니라 승인도 포함됩니다.
• 상호 작용. 귀하의 샘플 의견은 "왜 이것을 했습니까?"입니다. 매우 전형적인 것입니다. 댓글 전용 접근 방식은 대화를 지원하지 않습니다. 사람은 코드를 변경하고 주석을 삭제하거나 주석을 삭제할 수 있습니다. 그러나 "왜 이것을 했습니까?" "이것을 바꿔주세요. 틀렸어요"는 같은 것이 아닙니다.
• 기록 유지. 나중에 검토자가 코드가 실제로 변경되었는지 또는 주석이 방금 제거되었는지 확인할 수 있습니다. 또한 의견이 "기입"되었고 개발자가 더 이상 후속 검토에서 동일한 실수를하지 않는지 확인할 수 있습니다.

또한 검토를 수행하고 검토에 응답하기 위해 작업 항목을 사용하고 체크인을 연관시킵니다. 따라서 기존 변경 세트에서 주석을 쉽게 찾고 다른 변경 세트에서 각 주석이 어떻게 처리되었는지 확인할 수 있습니다.

다른 사람들은이 접근법의 한계에 대해 이야기했습니다. gerrit와 같은 도구는 설치하기 어렵다고 언급했습니다. phabricator (http://www.phabricator.com)를 살펴보십시오. 이것은 Facebook이 수년 동안 사용해 왔으며 최근에 오픈 소스 된 코드 검토 시스템입니다. 설치가 어렵지 않고 뛰어난 워크 플로우를 제공하며 다른 의견에서 언급 된 모든 문제를 해결합니다.