메소드의 서명에서 모든 매개 변수에 대한 javadoc 주석을 작성해야합니까?

우리 팀의 개발자 중 하나는 메소드의 서명에 모든 매개 변수에 대한 javadoc 주석을 작성해야한다고 생각합니다. 나는 이것이 필요하다고 생각하지 않으며 실제로는 그것이 해로울 수도 있다고 생각합니다.

먼저 매개 변수 이름은 설명적이고 자체 문서화되어야한다고 생각합니다. 매개 변수가 무엇인지 즉시 분명하지 않으면 아마도 잘못하고있을 것입니다. 그러나 매개 변수가 무엇인지 명확하지 않은 경우가 있으므로 이해합니다. 그렇다면 매개 변수를 설명하는 javadoc 주석을 작성해야합니다.

그러나 모든 매개 변수에 대해 그렇게 할 필요는 없다고 생각합니다. 매개 변수의 내용이 이미 명백한 경우 javadoc 주석은 중복됩니다. 당신은 자신을 위해 추가 작업을 만들고 있습니다. 또한 코드를 유지 관리해야하는 사람을 위해 추가 작업을 작성하고 있습니다. 시간이 지남에 따라 메소드가 변경되므로 주석을 유지하는 것이 코드를 유지하는 것만큼이나 중요합니다. "X는 Y에 대해 Y를 표시합니다"와 같은 주석을 몇 번이나 보았으며 주석이 오래되었고 실제로이 방법은 더 이상 X 매개 변수를 사용하지 않습니까? 사람들은 댓글 업데이트를 잊어 버리기 때문에 항상 발생합니다. 오해의 소지가있는 코멘트는 코멘트가 전혀없는 것보다 더 해롭다 고 주장합니다. 따라서 과도한 주석 처리의 위험이 있습니다. 불필요한 문서를 작성하면

그러나 나는 팀의 다른 개발자를 존중하며 그가 옳고 내가 틀렸다는 것을 인정합니다. 동료 개발자에게 질문을하는 이유는 무엇입니까? 실제로 모든 매개 변수에 대한 javadoc 주석을 작성해야합니까? 여기서 코드는 회사 내부에 있으며 외부에서 사용하지 않는다고 가정하십시오.

자바 독 (과, 마이크로 소프트 워드에 해당 xmldoc) 주석이없는 의견은 , 그들이 있습니다 문서 .

주석은 원하는만큼 희박 할 수 있습니다. 코드를 반쯤 읽을 수 있다고 가정하면 일반적인 주석은 단지 미래 개발자가 이미 2 시간 동안 응시 한 코드를 이해 / 유지하는 데 도움이되는 푯말 일뿐입니다.

이 문서 는 코드 단위와 호출자 간의 계약을 나타냅니다 . 공개 API의 일부입니다. 항상 그 자바 독 / 해당 xmldoc은 도움말 파일 또는 자동 완성 / 인텔리 / 코드 완성 팝업에서 하나 끝날 것, 그리고 사람들에 의해 관찰 할 생각 하지 코드의 내부를 검사하지만, 단순히하고자하는 사용 의 몇 가지 목적을 자신의.

인수 / 매개 변수 이름은 설명 이 필요 없습니다 . 당신은 항상 코드를 작성하는 데 하루를 보낸 적이 있다고 생각 하지만 2 주 휴가 후에 다시 돌아 오면 실제로 얼마나 도움이되는지 알 수 있습니다.

나를 오해하지 마십시오-변수와 인수에 의미있는 이름을 선택하는 것이 중요합니다. 그러나 이것은 문서 문제가 아니라 코드 문제입니다. 문자 그대로 "자체 문서화"라는 문구를 사용하지 마십시오. 이는 외부 문서 (계약)가 아닌 내부 문서 (설명)와 관련이 있습니다.

모든 것을 언급하거나 아무 것도 언급하지 마십시오 (분명히 모든 것을 언급하는 것이 훨씬 더 나은 선택입니다). 소스 파일 또는 생성 된 doc 파일 (예 : doxygen 출력)에서 직접 API를 검토하여 코드를 사용하는 사람을 생각해보십시오. 불일치는 일반적으로 혼동을 일으켜 소스를 조사 하는 데 시간이 걸리고, 왜 주석이 달리지 않은 이유를 알아 내고 , 매개 변수가 처음에 주석 처리 된 경우 피할 수 있었던 시간을 낭비하게됩니다.

기억하십시오 : 당신이 생각하는 것이 얼마나 평범한 지에 관계없이, 당신에게 의미가있는 것은 다른 사람에 의해 완전히 다르게 해석 될 수 있습니다 (영어를 읽고 코드를 이해하려고 노력하지 않는 사람에 대해 생각하십시오).

다른 개발자가 모든 것을 문서화하는 것의 중요성을 강조하고 있다면 문서를 최신 상태로 유지하는 데 많은 강조점을 두어야 합니다. 당신이 언급했듯이, 기한이 지난 주석보다 훨씬 나쁘지는 않습니다 (문서가 생략되지 않은 경우보다 나쁘지 않습니다).

개발자주기가 우리가 보존하려는 자원이라는 가정에서 시작합시다.

따라서 개발자는 자명 한 매개 변수와 반환 값을 문서화하는 데 시간을 낭비해서는 안됩니다.

글쎄, 그것을 분해하자.

한계 주석이 실제로 사소하고 생각이나 연구가 필요하지 않다고 가정하면 모든 것을 문서화하면 비용은 실제로 주석을 입력하고 오타를 수정하는 데 추가되는 시간입니다.

우리가 선택하고 선택하면 비용은 다음과 같습니다.

• 모든 것을 문서화해야한다고 생각하는 팀의 다른 개발자와 논쟁을 벌이고이기십시오.
• 각 매개 변수에 대해 문서화해야하는지 여부를 결정하십시오.
• 매개 변수를 문서화해야하는지 여부에 대해 다른 의견이있는 경우 팀과의 추가 논의
• 자명하다고 여겨지는 매개 변수가 그렇지 않은 것으로 밝혀지면 코드를 찾아 내고 조사하는 데 시간이 걸립니다.

그래서 나는 모든 것을 문서화하는 경향이 있습니다. 단점은 명확하지만 포함되어 있습니다.

어쨌든 Javadoc을 작성하는 경우 "명백한"매개 변수를 포함하여 Javadoc을 완전히 작성할 수도 있습니다. 그것들은 당신이나 다른 개발자에게 명백 할 수도 있지만, 그것을보고있는 새로운 사람이라면 각 매개 변수의 의도를 아는 것이 도움이 될 것입니다.

Javadoc을 올바로 유지 관리하려면 개발에 도움이되는 도구를 사용해야합니다. 이클립스 가 떠오른다. 물론 중요한 경우 팀의 모든 사람이 주석을 포함하여 코드를 유지하기 위해 자신의 역할을 수행하도록해야합니다.

코드와 분리 된 상태에서 javadoc을 표시 할 수 있다는 것을 잊지 마십시오 (예 : Java API 자체). 메소드에 모든 매개 변수에 대한 javadoc을 포함시키지 않으면 메소드가 잘못 표시되고 사용 방법이 잘못되었습니다.

'필수'는 완전히 주관적입니다. 나는 당신이 묻는 것은 '당신의 상황에서, 당신은 javadoc 주석을 추가 해야 합니다 '라고 생각합니다 . 앱의 범위 또는 컨텍스트를 모르는 경우 적절한 것이 무엇인지 어떻게 알 수 있습니까?

이 공개 코드 (예 : API와 같이 다른 사람이 액세스 할 수있는 코드) 인 경우 모든 단일 매개 변수를 문서화하십시오. 독자가 당신만큼 프로젝트에 대해 알고 있다고 가정하지 마십시오. 그러나 그렇지 않으면 귀하와 귀하의 팀이 귀하의 결정을 내립니다.