코드 검토 주석을 작성하는 방법 

요약 

• 친절하게 대해.
• 당신의 추론을 설명하십시오.
• 문제를 지적하고 개발자가 결정할 수 있도록 명시적인 지침을 제공합니다.
• 개발자에게 복잡성을 설명하는 대신 코드를 단순화하거나 코드 주석을 추가하도록 장려하십시오.

예의 

일반적으로 코드를 검토하는 개발자에게 매우 명확하고 도움이 되는 동시에 정중하고 존중하는 것이 중요합니다. 이를 수행하는 한 가지 방법은 항상 코드에 대한 주석을 작성하고 개발자에 대한 주석을 작성하지 않는 것입니다. 항상 이 관행을 따라야 하는 것은 아니지만, 화를 내거나 논쟁이 될만한 말을 할 때는 반드시 사용해야 합니다. 예를 들면 다음과 같습니다.

나쁜 예 : "동시성으로 얻을 이점이 없을 때 왜 스레드를 사용 했습니까?"

좋은 예 :“여기의 동시성 모델은 실제 성능상의 이점 없이 시스템에 복잡성을 추가하고 있습니다. 성능상의 이점이 없기 때문에 이 코드를 여러 스레드 대신 단일 스레드로 만드는 것이 가장 좋습니다.”

이유를 설명해라 

위에서 언급 한 "좋은"예에 대해 한 가지 주목할 점은 개발자가 왜 내 의견을 말하고 있는지 이해하는 데 도움이 된다는 것입니다. 이 정보를 항상 검토 의견에 포함 할 필요는 없지만 의도, 권장하는 모범 사례 또는 제안이 코드 건강을 개선하는 방법에 대해 조금 더 설명하는 것이 적절한 경우가 있습니다.

가이드 제공 

일반적으로 리뷰어가 아닌 CL을 수정하는 것은 개발자의 책임입니다. 솔루션의 세부 설계를 하거나 개발자를 위한 코드를 작성할 필요는 없습니다.

그렇다고 해서 검토자가 도움이 되지 않아야 한다는 의미는 아닙니다. 일반적으로 문제 지적과 직접적인 지침 제공간에 적절한 균형을 유지해야 합니다. 문제를 지적하고 개발자가 의사 결정을 내리게 하면 개발자가 배우는 데 도움이 되고 코드 검토가 더 쉬워집니다. 또한 개발자가 검토 자보다 코드에 더 가깝기 때문에 더 나은 솔루션을 얻을 수 있습니다.

그러나 때로는 직접적인 지침, 제안 또는 코드가 더 도움이 됩니다. 코드 검토의 기본 목표는 최상의 CL을 얻는 것입니다. 두 번째 목표는 개발자의 기술을 향상 시켜 시간이 지남에 따라 검토가 덜 필요하다는 것입니다.

설명 수락 

개발자가 이해하지 못하는 코드를 설명하도록 요청하면 일반적으로 코드를 더 명확하게 다시 작성해야 합니다. 지나치게 복잡한 코드를 설명하는 것이 아니라면 코드에 주석을 추가하는 것도 적절한 응답입니다.

코드 검토 도구로만 작성된 설명은 향후 코드 리더에게 도움이 되지 않습니다. 익숙하지 않은 영역을 검토 할 때와 같이 몇 가지 상황에서만 사용할 수 있으며 개발자는 코드의 일반적인 독자가 이미 알고 있는 것을 설명합니다.