수업 문서 헤더에 포함해야 할 내용

엔티티, 비즈니스 로직 및 데이터 액세스 클래스에 대한 유익한 클래스 문서 형식을 찾고 있습니다.

여기 에서 두 가지 형식을 발견 했습니다.

형식 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

형식 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

기본 요소는 다음과 같습니다

• 저자
• 작성일
• 기술
• 개정 이력

네임 스페이스와 클래스 이름으로 어쨌든있을 것입니다.

귀하의 생각, 어떤 형식이 권장되며 개정 기록을 작성하는 표준 방법이 있는지 알려주십시오.

제안한 대부분의 정보는 소스 리포지토리에 있습니다.

당신이 정말로 필요로하는 것은 수업이 무엇인지 말하는 목적 섹션입니다.

다른 정보를 알고 싶을 때마다 저장소를 살펴 보는 것이 지루할까요? 나는 아니오라고 말할 것입니다. 원저자를 얼마나 자주 관리하십니까? 아니면 파일이 처음 만들어 졌을 때? 플러그인 (예 : Visual Studio 용 Ankh SVN)을 사용하면 현재 파일을 마우스 오른쪽 단추로 클릭하고 파일의 저장소 로그를 볼 수 있으므로 실제로이 정보를 보는 것이 그리 번거롭지는 않습니다.

또한 주석에 버전 기록을 저장하는 경우이 주석을 유지해야합니다. 시간이 지남에 따라 거짓말을 할 가능성이 있습니다. 소스 코드 저장소는이 히스토리 데이터를 자동으로 유지하므로 유지 보수가 필요하지 않으며 정확합니다.

설명적인 클래스, 메소드 및 변수 이름이 있어야합니다 . 이를 통해 목적 및 설명과 같은 의견이 필요하지 않습니다. 때로는 메서드 이름이 짧을수록 좋습니다. 반대로, 목적을 명확하게 설명하는 한 원하는 방법으로 분석법 이름을 만드십시오. 절대적으로 중요한 메모 만 있고 특정 방식으로 코드를 이해하는 데 도움이됩니다. 코드를 변경할 때 프로그래머는 종종 주석 업데이트를 잊어 버립니다. 주석과 코드가 동기화되지 않고 좋은 것보다 더 많은 피해를 줄 수 있습니다.

Jeff Atwood- 코딩없는 주석 으로이 기사를 읽으십시오 .

표준 태그를 사용하여 설명서를 생성합니다. 더 이상 아무것도 없습니다. 여길 봐

나는 수업에 속하지 않는 정보를 넣지 않습니다. 작성자, 데이터, 개정판은 버전 관리 시스템에 저장할 데이터입니다.

제시된 두 가지 형식은 문서를 생성하는 데 쓸모가 없으며 주석에 가장 큰 오류가 있으며 수정 내역을 나열합니다.

이 정보의 대부분은 소스 제어 저장소에 의해 추가 될 수 있으며, 클래스의 범위와 동작을 정확하게 설명해야하는 설명 만 남게됩니다. Java JDK에 대한 Javadoc 중 일부를 예로 들어 보는 것이 좋습니다.

그 목록에있는 모든 것은 불필요합니다. 소스 컨트롤은 거의 모든 것을 처리해야하며 다루지 않는 것은 좋은 명명 규칙에 의해 처리됩니다.

수업 내용을 파악하기 위해 "설명"을 읽어야하는 경우 (a) 이름을 잘못 지정했거나 (b) 너무 많은 작업을하는 나쁜 수업 (SRP)을 작성했습니다.

다른 사람들이 지적 했듯이이 정보는 리포지토리에서 찾을 수 있으며 지금까지 유지하려고했던 큰 필드는 다음과 같습니다. 헤더 템플릿을 변경하는 데 어려움을 겪었습니다.

• 설명 -코드에서 수행중인 작업
• 참고 -코드 자체의 주석에서 쉽게 파생되지 않는 코드에 대해 알아야 할 사항
• 참조 -코드가 의존하는 참조는 사용 include또는 유사한 명령문을 통해 명확하지 않습니다 .

도 포함하는 것이 유용 할 수 있습니다 하나 개의 항목에 대한 섹션 키워드 는 함수, 클래스, 구조체 등의 이름에 대한 검색을 할 수있을 수도 있지만, 파일에 다른 이름을 명확하게하지 않는 것이 몇 가지 키워드가있을 수 있습니다. 또는 잘못 문서화 된 오래된 코드의 경우 유지 보수를 위해 코드를 문서화하는 첫 번째 단계 일 수 있습니다.

내가 지금까지 읽은 다른 답변의 대부분은 항상 사용할 수있는 하나의 저장소 만 있다고 가정했습니다.

소스 코드는 저장소에 대한 연결을 잃을 수 있기 때문에 (즉, 복사 된 경우) 내 클래스 문서는 다음과 같습니다.

• class documentation header (= 파일 시작 부분의 주석 블록)에는 필요한 법적 정보 만 포함됩니다 (즉, gpl 라이센스하에 xyz의 저작권)
• 클래스를 사용하는 개발자가 알아야 할 모든 것은 class-java-doc-comments (또는 이와 동등한 .net)로 이동하여 최신 아이디어가 클래스를 사용하는 소스 코드에서 툴팁 정보 로이 정보를 표시 할 수 있도록하십시오.

또한 버그 수정 또는 기능 요청에 대한 티켓 번호를 추가하여 클래스가 생성 된 위치 / 시간 / 이유를 알 수 있습니다 (만약 운이 좋으면 몇 년 후에도 티켓에 계속 액세스 할 수있는 경우).

구식 폐쇄 소스 레거시 프로그램에서 문제를 해결하라는 요청을 받았을 때 티켓 번호는 코드의 원래 요구 사항을 이해하는 데 매우 가치가 있습니다.