최근에 나는 현재 다루고있는 코드베이스의 일부를 리팩토링하는 일을 해왔다. 나 자신을 더 잘 이해하고있을뿐 아니라 코드를 다루는 다른 사람들이 더 쉽게 이해할 수 있도록하기 위해서다.
나는 그 생각의 측면에 의지하는 경향이 자기 문서화 코드가 좋은 것입니다 . 나는 그것이 더 깨끗하다고 생각하고 코드가 스스로를 말하면 글쎄 ... 훌륭 합니다.
반면에 우리는 javadocs와 같은 문서를 가지고 있습니다. 나는 이것도 좋아하지만 여기의 주석이 구식이 될 위험이 있습니다 (물론 일반적인 주석뿐만 아니라). 그러나 최신 버전이라면 복잡한 알고리즘을 이해하는 것이 매우 유용 할 수 있습니다.
이에 대한 모범 사례는 무엇입니까? 자체 문서화 코드와 javadoc 사이의 경계선은 어디에 있습니까?
답변:
자체 문서화 코드 (및 코드 내 주석)와 Javadoc 주석은 대상 독자가 매우 다릅니다.
코드 파일에 남아있는 코드와 주석은 개발자를위한 것입니다. 여기에서 그들의 우려를 해결하고자합니다. 코드가하는 일과 코드가 왜 그런지 이해하기 쉽게 만드십시오. 주석과 함께 적절한 변수 이름, 메소드, 클래스 등 (자체 문서화 코드)을 사용하면이를 달성 할 수 있습니다.
Javadoc 주석은 일반적으로 API 사용자를위한 것입니다. 이들은 또한 개발자이지만 시스템의 내부 구조, 시스템의 클래스, 메소드, 입력 및 출력에 대해서는 신경 쓰지 않습니다. 코드는 블랙 박스 안에 들어 있습니다. 이 주석은 특정 작업을 수행하는 방법, 예상되는 작업 결과, 예외 발생시기 및 입력 값의 의미를 설명하는 데 사용해야합니다. Javadoc에서 생성 한 문서 세트가 제공되므로 코드를 보지 않고도 인터페이스 사용 방법을 완전히 이해할 수 있어야합니다.
코드는 어떻게 말한다 . 댓글은 말할 이유 , 그리고 심지어 왜 안 .
미래의 독자와 코드 관리자에게 모두 제공하는 것이 귀하의 임무입니다. 코드에는 가능하고 나머지는 주석에 넣으십시오.
캡처하기 가장 어려운 것은 디자인 결정이므로 이러한 사항도 기억하십시오.
Javadocs를 사용해도 큰 차이는 없습니다. 생성 된 문서에는 주석의 텍스트와 함께 함수 이름이 포함되므로 주석에서 함수 이름 자체에서 분명한 내용을 반복해야하는 이유는 전혀 없습니다.
반면에, 구현이 무엇인지 이해하기 위해 먼저 구현을 살펴 봐야하는 기능이있는 경우 (따라서이 정보를 Javadocs에 제공하지 않음) 코드는 자체 문서화되지 않습니다. 구현이 얼마나 명확한 지.
javadocs의 경우 모든 문서와 동일하다고 생각합니다. 주된 규칙은 다음과 같습니다.
마 많은 사람들이 당신의 javadoc을 읽을? 그렇다면 올바른 노력을 기울이는 것이 좋습니다.
독자들은 javadoc을 공부하기 위해 코드 읽기 를 건너 뛰는 경향이 있습니까? 그렇다면 글쓰기에 노력을 기울이는 것이 두 배의 의미가 있습니다.
자, 당신의 경우입니까? 그렇지 않다면, javadocs에 투자 한 노력이 정당한지 두 번 생각하십시오.
위에서 지적했듯이 청중의 말을 들어 길을 찾으십시오.
Javadoc 주석이 오래 될 수 있다는 우려에 대해 언급하고 싶습니다. @JonathanMerlet은 Javadoc이 안정적이어야한다고 말하고 있지만, 동료 검토 중에 Javadoc과 주석 및 코드를 검토하여 도움을 줄 수도 있습니다. 주석이 코드가 수행하는 작업과 일치합니까? 그렇지 않은 경우, 이는 올바르지 않으며 개발자가 수정하도록 주장하십시오. 다른 개발자들도 그렇게하도록 격려하십시오. 이를 통해 외부 문서 (Javadoc 주석)를 최신 상태로 유지할뿐만 아니라 일반 코드 주석도 유지할 수 있습니다. 이를 통해 리팩토링을 수행 한 개발자는 코드를보다 빠르고 쉽게 이해할 수 있으며 향후 유지 관리가 훨씬 간단 해집니다.