Robert C. Martin의 인용문은 문맥에서 벗어납니다. 약간 더 많은 문맥을 가진 인용문은 다음과 같습니다.
잘 배치 된 의견만큼 도움이 될만한 것은 없습니다. 사소한 독단적 인 의견 이상의 모듈을 어수선하게 만들 수있는 것은 없습니다. 거짓말과 잘못된 정보를 전파하는 오래된 잔인한 의견만큼 큰 피해는 없습니다.
댓글은 쉰들러의 목록과 다릅니다. 그들은 "순수하지 않다". 실제로, 의견은 기껏해야 필요한 악입니다. 우리의 프로그래밍 언어가 충분히 표현력이 있거나 의도를 표현하기 위해 그 언어를 미묘하게 사용하는 재능이 있다면, 우리는 전혀 언급하지 않아도 될 것입니다. 아마도 아닙니다.
주석의 올바른 사용은 코드로 자신을 표현하지 못한 것을 보상하는 것입니다. 나는 실패라는 단어를 사용했습니다. 나는 그것을 의미했다. 주석은 항상 실패입니다. 우리는 항상 그들없이 자신을 표현하는 방법을 알 수 없기 때문에 그것들을 가져야하지만, 그것들의 사용이 축하의 원인이 아닙니다.
따라서 의견을 작성해야 할 위치에있을 때 의견을 검토하고 표를 돌리고 코드로 표현할 수있는 방법이 없는지 확인하십시오. 코드로 자신을 표현할 때마다 등을 두 드려야합니다. 당신이 의견을 쓸 때마다, 당신은 얼굴을 찡그리고 표현력의 실패를 느껴야합니다.
( 여기서 복사 했지만 원래 인용문은 Clean Code : Handbook of Agile Software Craftsmanship )입니다.
이 인용문이 "코멘트는 항상 실패"로 축소되는 방법은 일부 사람들이 문맥에서 현명한 인용을 취해 어리석은 교리로 바꾸는 좋은 예입니다.
javadoc과 같은 API 문서 는 사용자가 소스 코드를 읽을 필요없이 API를 사용할 수 있도록 API를 문서화해야 합니다 . 따라서이 경우에는 문서 한다 방법이 무엇을하는지 설명한다. 이제 메소드 이름으로 이미 표시되어 있기 때문에 "ID로 제품 검색"이 중복 적이라고 주장 할 수 있지만 null
리턴 될 수 있는 정보는 명백한 방식이 아니기 때문에 문서화에 반드시 중요합니다.
주석의 필요성을 피 null
하려면 API를보다 명시 적으로 작성하여 근본적인 문제점 ( 유효한 리턴 값으로 사용)을 제거해야합니다 . 예를 들어 Option<Product>
, 어떤 유형의 유형을 리턴 할 수 있으므로 유형 서명 자체는 제품을 찾을 수없는 경우 리턴 될 내용을 명확하게 전달합니다.
그러나 어쨌든 메소드 이름과 유형 서명을 통해 API를 완전히 문서화하는 것은 현실적이지 않습니다. 명확하지 않은 추가 정보에 대해서는 doc-comments를 사용하십시오. DateTime.AddMonths()
BCL 에서 API 문서를 말하십시오 .
AddMonths 메서드는 윤년과 한 달의 일 수를 고려하여 결과 월과 연도를 계산 한 다음 결과 DateTime 객체의 요일 부분을 조정합니다. 결과 날짜가 결과 월의 유효 날짜가 아닌 경우 결과 월의 마지막 유효 날짜가 사용됩니다. 예를 들어, 3 월 31 일 + 1 개월 = 4 월 30 일입니다. 결과 DateTime 객체의 시간 부분은이 인스턴스와 동일하게 유지됩니다.
메소드 이름과 서명 만 사용하여이를 표현할 수있는 방법은 없습니다! 물론 클래스 문서는이 수준의 세부 사항을 요구하지 않을 수 있습니다. 이는 단지 예일뿐입니다.
인라인 주석 도 나쁘지 않습니다.
나쁜 의견은 나쁘다. 예를 들어 코드에서 사소하게 볼 수있는 내용 만 설명하는 주석은 고전적인 예입니다.
// increment x by one
x++;
변수 나 메소드의 이름을 바꾸거나 코드를 재구성하여 명확하게 설명 할 수있는 설명은 코드 냄새입니다.
// data1 is the collection of tasks which failed during execution
var data1 = getData1();
이것들은 마틴 레일즈에 대한 의견입니다. 주석은 명확한 코드를 작성하지 못한 경우의 증상입니다.이 경우 변수 및 메소드에 대해 자명 한 이름을 사용하십시오. 주석 자체는 물론 문제가 아니며 문제는 코드를 이해하기 위해 주석이 필요하다는 것입니다.
그러나 주석은 코드에서 명확하지 않은 모든 것을 설명하는 데 사용해야 합니다. 예를 들어 코드가 분명하지 않은 방식으로 작성된 이유 는 다음과 같습니다.
// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();
지나치게 복잡한 코드 조각이하는 일을 설명하는 주석도 냄새이지만, 수정은 주석을 금지하지 않으며 수정은 코드 수정입니다! 실제로 복잡한 코드가 발생하지만 (리팩터링까지 일시적으로 만 가능) 일반 개발자는 처음으로 완벽한 코드를 작성하지 않습니다. 복잡한 코드는 그것보다 무엇을 설명하는 코멘트를 작성하는 훨씬 더 발생하면 되지 코멘트를 작성합니다. 이 의견은 또한 나중에 쉽게 리팩토링 할 수있게합니다.
때때로 코드는 불가피하게 복잡합니다. 복잡한 알고리즘 일 수도 있고 성능상의 이유로 명확성을 희생하는 코드 일 수도 있습니다. 다시 의견이 필요합니다.