Javadoc @author 태그 우수 사례

Javadoc @author 태그 우수 사례

---

Javadocs를 만들 때 모범 사례에 대해 궁금합니다. 파일이 많은 프로젝트가 있습니다. 코드는 많은 개발자가 만들었습니다. 각 파일에는 주석 @author이 있으므로 특정 클래스를 만든 사람이 분명합니다.

하지만 다른 개발자가 파일에 새 코드를 추가하고 수정하는 등의 경우에는 나머지 팀에게 새 함수를 만들었거나 기존 코드를 수정했음을 어떻게 알려야합니까? 다시 말해서, 어떻게 "Javadocs를 현실과 호환되도록 유지"해야합니까? ;)

• 기존 @author태그에 그의 이름을 추가 하시겠습니까? 그러면 의심스러운 경우 누구에게 물어볼 것인지 식별하는 것이 더 쉽습니다.
• @author각각의 새 메소드, 내부 클래스 등에 태그를 추가 하시겠습니까?

물론 SVN을 사용하기 때문에 누가 무엇을 만들 었는지 조사하기는 쉽지만 명확하게 유지하려면이 Javadoc 항목도 고려해야합니다.

이 @author태그 를 사용하는 가장 좋은 방법은 무엇입니까 ?

---

나는 대부분의 목적 @author에서 원하지 않는 소음 이라고 말하고 싶습니다 . API 사용자는 누가 어떤 부분을 작성했는지는 신경 쓰거나 알고 싶어해서는 안됩니다.

그리고 이미 언급했듯이 SVN은 이미 코드가 할 수있는 것보다 훨씬 더 권위있는 방식으로이 정보를 보유하고 있습니다. 따라서 내가 팀 중 하나라면 항상 SVN의 로그를 선호하고 @author. 나는 당신이 채택한 정책이 무엇이든간에 코드가 현실과 일치하지 않을 것이라고 확신합니다. 자신을 반복하지 마십시오 원칙에 따라 왜이 정보를 두 곳에 보관합니까?

그러나이 정보가 반드시 코드에 포함되어야하는 관료적 또는 정책적 이유가 @author있는 경우 체크인시 코드 의 태그를 자동으로 업데이트하는 것을 고려 했습니까? 당신은 할 수 아마도 SVN 후크와이를 달성. 예를 들어 주어진 파일을 변경 한 순서대로 변경 한 모든 개발자를 나열 할 수 있습니다. 또는 누가 가장 많이 바꿨는지; 또는 무엇이든. 또는 @author외부 세계에 릴리스하는 (소스) 코드에서 필수 사항 @author인 경우 릴리스 빌드의 일부로 자동으로 추가하는 것을 고려할 수 있습니다 (어떻게 든 SVN에서이 정보를 얻을 수 있다고 생각합니다).

하나 이상의 클래스 레벨 @author태그 (또는 다른 코멘트) 를 추가하는 것에 관해서 는 많은 도움이되지 않는 소음이 쌓이게 될 것입니다. (다시 SVN이 있습니다.)

내 경험상 역사적 변경 (예 : 코드 줄 또는 메서드의 변경)을 식별 한 다음 이것이 어떤 변경 세트와 관련된 (그리고 어떤 트랙 티켓)을 파악하는 것이 훨씬 더 유용합니다. 그러면 변경에 대한 전체 컨텍스트가 있습니다. 티켓, 변경 세트가 있고 동일한 티켓에서 다른 변경 세트를 찾거나 거의 같은 시간에 관련 티켓을 찾을 수 있으며 모든 변경 사항을 볼 수 있습니다. 그 작업 단위를 형성했습니다. 코드의 주석이나 주석에서 이것을 얻을 수는 없습니다.

---

소스에 작성자 태그가 필요한 이유 를 고려할 수 있습니다 . Apache Foundation은 그렇지 않으며 동의합니다.

http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

내가 가장 잘 이해하기 위해 이것은 소스가 종이에 인쇄되었을 때 작업하는 카고 컬트 방식입니다. 최신 버전 제어 시스템을 사용하면이 정보 등을 역사에서 찾을 수 있습니다.

---

둘 이상의 @author태그를 가질 수 있습니다 . 클래스를 크게 변경 한 경우 @author자신의 이름이 포함 된 새 태그를 추가하면 됩니다. 변경 사항을 표시하거나 변경 사항 주변에 이름을 넣을 필요가 없습니다. 업데이트 내역이이를 명확하게 표시 할 수 있어야하기 때문입니다.

---

많은 개발자가 참여하는 매우 크고 장기적인 프로젝트에서, 추가 정보 등을 제공 할 수있는 주어진 코드에 대해 ho가 책임이 있음을 아는 것이 유용합니다. 이 경우 @author 태그를 사용하여 파일에 이러한 정보를 포함하는 것이 편리합니다. 누가 파일을 만들 었는지 또는 누가 주요 기여를했는지 표시하지 않고 해당 코드에 대한 연락 담당자입니다. 원저자가 이미 다른 프로젝트에 참여했거나 몇 년 전에 회사를 떠났기 때문에 이들은 매우 다른 사람들 일 수 있습니다.

나는 접근이 편리 할 수있는 거대한 프로젝트에 대해 생각하지만주의 할 점이있다. 엄청난 양의 파일이 있고 조만간 실패하므로 모든 파일의 작성자 정보를 유지하는 것은 매우 어렵습니다. 점점 더 많은 파일에 오래된 정보가 포함될 것이며 개발자는 더 이상이 @author를 정보 소스로 신뢰하지 않고 무시할 것입니다.

작동 할 수있는 해결책은 모든 단일 파일에 @author를 유지하는 것이 아니라 모듈 (높은 수준의 패키지)별로 만 유지하는 것입니다. Javadoc에는 파일뿐만 아니라 전체 패키지를 문서화 할 수있는 기능이 있습니다 ( 자세한 내용은이 질문 참조 ).

그러나 이것은 특별한 경우이며 귀하의 프로젝트가 그렇게 크거나 오래되지 않는 한 저자 정보를 생략하는 것이 좋습니다.

---

나는 그것이 불필요하다는 데 전적으로 동의하며 아마 추가해서는 안됩니다. 그러나 나는 여전히 그것을 추가합니다. 그림에 서명을 추가 하거나 컴퓨터의 금속 조각에 스탬프를 추가하여 디자인에 도움이되는 것처럼 보입니다.. 이 코드를 작성하고 이름을 추가하면 코드가 자랑스럽고 품질에 대한 확신이 있음을 알 수 있습니다. 나중에 변경 되더라도 그 위에 구축 된 모든 것의 토대를 마련했으며 실제로 완전히 다시 작성하면 태그를 변경, 제거 또는 확장 할 수 있습니다. 버전 관리 덕분에 중복된다는 데 동의하지만 버전 관리에 이름이있는 것은 거의 만족스럽지 않습니다. 누군가 "최종"을 추가하거나 코드 형식을 지정하면 거의 기여하지 않더라도 이름이 버전 관리에 포함됩니다. 나는 또한 코드에 아무것도 추가하지 않는다는 점에서 소음이라는 데 동의하지만 실제로 약간 눈에 띄게 성가신가요? 나는 그렇게 생각하지 않는다. 합리적이라면 프로젝트를 만들 수 있다고 생각합니다. "

---

@author 태그가 있고 여러 작성자가있는 것이 매우 편리합니다. Oracle의 문서조차도 작업을 수행 한 특정 작성자에게 크레딧을 제공하고 개발 프로세스 중에 누군가와 대화해야하는 경우 작업을 추적하기 위해 클래스 맨 위에 @author를 두는 것이 좋습니다. 여러 작성자가있는 경우 특정 Java 파일 / 클래스에 기여한 순서대로 나열 할 수 있습니다. 예, 플러그인이 있고 git 구조를 사용하면 코드에있는 작성자의 이름을 정확하게 확인할 수 있지만이 아이디어는 논란의 여지가 있습니다. 때로는 여러 작성자가 동일한 코드 행을 편집하고 두 작성자가 동일한 코드 행을 편집하는 것을 보여주지 않을 수 있기 때문입니다. 플러그인을 사용하도록 설정했으며 동일한 코드 줄을 편집하기 위해 2 명의 작성자 이름을 표시하지 않습니다. 대기업의 경우이 관행을 설정하는 것이 편리합니다.

---

회사 코드라면 그렇게하지 않을 것입니다. VCS가 있습니다. 대신 블로그 게시물이나 내 개인 저장소의 코드 스 니펫 인 경우 자랑스럽게 추가하고 일부 복사-붙여 넣기 녀석이 내 코드가 유용하고 우연히 내 이름을 복사하기를 바랍니다. :)

제 유형의 유머입니다.

참조 URL : https://stackoverflow.com/questions/17269843/javadoc-author-tag-good-practices