How to write code review comments

본 문서는 google code review guide를 보고 요약한 글 입니다.

몇 가지 원칙이 있습니다.

• 친절하게 하세요.
• 당신이 그렇게 생각한 이유를 설명하세요.
• 문제를 지적하고 코드 작성자가 결정할 수 있게하거나 명시적인 지침을 제공하세요.
• 코드 작성자가 복잡한 코드를 리뷰어에게 설명하는 대신 코드를 단순화 하거나 주석을 추가하도록 말해주세요.

1. 예의 (Courtesy)

일반적으로 리뷰어는 코드 작성자에게 도움이 되는 동시에 정중하고 공손해야 합니다. 이를 수행하는 한 가지 방법은 항상 코드에 대한 의견(comment)만을 작성하고, 코드 작성자에 대한 의견을 작성하지 않는 것 입니다. 항상 이 방법을 따라야 할 필요는 없지만 화를 내거나 논쟁적인 어조로 말을 하게 되면 반드시 이 방법을 사용해야 합니다. 아래의 예시를 참고하세요.

• BAD: “동시성으로 얻는 이점이 없는데 왜 thread를 사용한거죠?”

• GOOD: “여기서 동시성 모델을 사용하면 실제 성능상의 이점 없이 코드의 복잡성이 증가됩니다. 성능상의 이점이 없기 때문에 여러 thread 대신 단일 thread를 만드는 것이 가장 좋습니다.”

2. 이유를 설명하기 (Explain Why)

위에 언급한 “GOOD”에서 주목할 점은, 코드 작성자가 리뷰어의 의견을 이해하는데 도움이된다는 점입니다. 리뷰어는 이러한 정보를 항상 의견에 포함할 필요는 없습니다. 하지만 리뷰어의 의도, 리뷰어가 따르고 있는 모범사례(best practice) 혹은 리뷰어의 제안이 어떻게 코드의 품질을 향상시키는지에 대해, 좀 더 많은 설명을 하는 것이 적절합니다.

3. 가이드 제공하기 (Giving guidance)

일반적으로 CL을 수정하는 것은 리뷰어가 아니라 코드 작성자에게 책임이 있습니다. 그렇기 때문에, 리뷰어가 세부 설계를하거나 코드 작성자를 위해 코드를 작성할 필요는 없습니다.

그렇다고해서, 리뷰어가 도움을 주지 않아야한다는 의미는 아닙니다. 일반적으로 문제 지적과 직접적인 가이드(direct guidance)을 제공하는 것 간에 적절한 균형을 유지해야 합니다. 문제를 지적하고 코드 작성자가 결정을 내리게 하면 학습하는데 도움을 주게되고, 코드 작성자의 수준이 올라감에 따라 더 쉬운 리뷰를 할 수 있게 됩니다. 또한 코드 작성자가 리뷰어보다는 자신이 작성한 코드를 더 잘 알수있기 때문에, 리뷰어보다 나은 해결책을 찾을 수 있습니다.

코드 리뷰의 첫 번째 목표는 최상의 CL을 작성하는 것입니다. 두 번째 목표는 코드 작성자의 기술을 향상시켜 시간이 지남에 따라 리뷰가 덜 필요하게 만드는 것입니다. 때문에 직접적인 가이드, 제안, 코드가 코드 작성자에게 더 도움이 될 때가 있습니다.

4. 코드 작성자의 설명 받아들이기 (Accepting explanations)

만약 리뷰어가 리뷰어가 이해하지 못하는 코드의 설명을 코드 작성자에게 요청하면, 보통 코드 작성자가 코드를 다시 명확하게 작성해야 합니다. 때때로 지나치게 복잡한 코드를 설명하는 것만 아니라면 주석을 추가하는 것도 적절한 대응입니다.

코드 리뷰 툴에만 쓰여진 설명은 나중에 코드를 읽게 될 개발자들에게 도움이 되지 않습니다. 따라서 리뷰 툴에 설명을 작성하는 경우는 평소 코드 작성자들은 잘 알지만 리뷰어만 모르는 내용이 있다던지 하는 경우로 제한되어야 합니다.