헤더 파일이나 소스 파일에 함수를 문서화하는 것이 더 낫습니까?

"소스"와 "헤더"파일 (주로 C와 C ++)을 구분하는 언어에서는 헤더 파일에 함수를 문서화하는 것이 좋습니다.

( CCAN 에서 인용 )

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

또는 소스 파일에서?

(PostgreSQL에서 인용)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

구조체, 매크로 및 static inline함수 와 같은 일부 항목은 헤더에만 정의되어 있습니다. 헤더 파일에 선언 되어 소스 파일에 정의 된 것들에 대해서만 이야기하고 있습니다.

내가 생각할 수있는 몇 가지 주장이있다. 소스 파일에 문서화하는 데 집중하고 있으므로 "Pro-header"인수가 다소 약할 수 있습니다.

프로 헤더 :

• 사용자는 설명서를보기 위해 소스 코드가 필요하지 않습니다.
  • 소스를 얻는 것이 불편하거나 불가능할 수도 있습니다.
  • 이것은 인터페이스와 구현을 더 멀리 유지합니다.

프로 소스 :

• 헤더를 훨씬 짧게 만들어 독자에게 모듈 전체를 조감 할 수 있습니다.
• 함수의 문서를 구현과 결합하여 함수가 말하는 기능을 쉽게 수행 할 수 있습니다.

대답 할 때 도구와 "현대 IDE"가 할 수있는 일에 근거한 논쟁에주의하십시오. 예 :

• 프로 헤더 : 코드를 접 으면 주석을 숨겨 주석이 달린 헤더를보다 쉽게 ​​탐색 할 수 있습니다.
• Pro-source : cscope 의 Find this global definition기능은 헤더 파일 ( 선언 이 있는)이 아니라 소스 파일 ( 정의 가있는)로 이동합니다 .

나는 그런 주장을하지 않는다고 말하는 것이 아니라, 모든 사람이 당신이 사용하는 도구에 익숙하지 않다는 것을 명심해야한다.

내 견해 ...

• 헤더 파일에서 함수를 사용하는 방법을 문서화하거나 선언에 더 가깝게 문서화하십시오.

• 소스 파일에서 함수가 어떻게 작동하는지 (코드에서 명확하지 않은 경우) 정의에 더 가깝게 문서화하십시오.

헤더의 조감도에 대해서는 반드시 가까운 문서가 필요하지 않습니다. 선언 그룹을 한 번에 문서화 할 수 있습니다.

광범위하게 말하면, 호출자는 오류와 예외에 관심을 가져야하며 (추상 계층을 통해 전파 될 때만 변환 될 수있는 경우에만) 관련 선언에 가깝게 문서화되어야합니다.

Doxygen 과 같은 도구를 사용하려는 경우 (첫 번째 예제에서는으로 시작하기 때문에 실제로 Doxygen 주석처럼 보입니다 /**) 실제로 중요하지 않습니다 .Doxygen은 헤더와 소스 파일을 살펴보고 찾습니다. 모든 주석은 문서를 생성합니다.

그러나 선언이있는 헤더에 문서 주석을 넣는 경향이 더 큽니다. 클라이언트는 소프트웨어와 인터페이스하기 위해 헤더를 처리 할 것이고, 헤더는 자신의 소스 파일에 포함 할 것이므로 API가 어떻게 보이는지 먼저 살펴볼 것입니다.

예를 들어 대부분의 Linux 라이브러리를 살펴보면 Linux 패키지 관리 시스템에는 라이브러리의 바이너리 만 포함 된 패키지 (라이브러리가 필요한 프로그램이있는 "일반적인"사용자) 만 포함하는 패키지가 있고 "dev"패키지가 있습니다. 라이브러리의 헤더를 포함합니다. 소스 코드는 일반적으로 패키지에 직접 제공되지 않습니다. API 문서를 얻기 위해 어딘가에 라이브러리의 소스 코드를 가져와야하는 경우 정말 번거로울 것입니다.

소스 파일에서 사용할 수 있고 awk 스크립트 (공포)로 스캔 할 수있는 #defines (예 : <nothing>으로 변환 된 공개, 개인 등)를 만들어이 문제를 해결했습니다 (약 25 년 전). !) .h 파일을 자동 생성합니다. 이는 모든 주석이 소스에 존재하고 생성 된 .h 파일에 (적절한 경우) 복사되었음을 의미합니다. 나는 그것이 올드 스쿨이라는 것을 알고 있지만, 이런 종류의 인라인 문서를 크게 단순화했습니다.

이 큰 프로젝트에서 코드입니다 가정 (개발자는 종종 소스와 헤더 사이를 이동하는 것) ,이 제공하는 것이 아닌 다른 사람이 소스에 액세스 할 수 없습니다 도서관 / 미들웨어, 나는이 작품을 발견했습니다 베스트...

• 머리글 :
  필요한 경우에만 1-2 줄 주석을 입력하십시오.
  때때로 관련 기능 그룹 위의 주석도 도움이됩니다.
• 출처 :
  함수 바로 위에있는 API에 대한 문서 (원하는 경우 일반 텍스트 또는 독소) .
• 함수 본문에서 코드를 수정하는 개발자와 만 관련하여 구현 세부 사항을 유지하십시오.

이것의 주된 이유는 주석을 코드에 가깝게 유지하는 것입니다. 헤더의 문서는 코드 변경과 더 자주 동기화되지 않는 경향이 있음을 알았습니다 (물론 그렇지 않아야하지만 프로젝트에서 최소한) . 또한 개발자는 헤더 문서가 있거나 다른 곳이 있더라도 약간의 변경을 할 때 함수 상단에 문서를 추가 할 수 있습니다. 더블 업 또는 유용한 정보가 문서 문자열 중 하나에 만 있도록합니다.

물론 컨벤션을 선택하고 모든 개발자가 준수하도록 할 수 있습니다. 컨벤션은 가장 자연스럽게 적합 하며 유지 관리에 문제가 거의 없습니다.

마지막으로, 대규모 프로젝트의 경우- 다른 사람들이 버전 제어를 업데이트 할 때 잠재적으로 100 또는 1000 파일의 파일이 다시 컴파일 될 것이라는 것을 알 때 헤더에서 작은 수정을 하지 않는 경향 이 있습니다-bisecting 오류도 느려집니다.

내 (제한적이고 편견이 아닌) 의견으로는, 나는 소스 코드 사고 방식입니다. C ++에서 비트와 조각을 할 때 일반적으로 헤더 파일을 한 번 편집 한 다음 절대 다시 돌아 가지 않습니다.

소스 파일에 문서를 배치하면 코드를 편집하거나 읽을 때 항상 문서가 표시됩니다. 그것은 습관적인 것 같아요.

하지만 그건 나 뿐이야

의견은 문서가 아닙니다. 함수에 대한 문서는 일반적으로 다이어그램과 함께 2K 텍스트 일 ​​수 있습니다 (예 : Windows SDK의 함수에 대한 문서 참조). 주석 투 독 (doc-to-doc)이 그러한 것을 허용하더라도 주석이 포함 된 코드를 읽을 수 없게 만듭니다. 문서를 작성하려면 워드 프로세서를 사용하십시오.

소스 코드의 이해 당사자 (예 : 소규모 라이브러리)가 "사용자"(구현에 관여하지 않고 라이브러리 기능을 사용하는 개발자)와 "개발자"(사용자 및 라이브러리를 구현할 다른 개발자)로 구성된 경우 그런 다음 "사용자 정보"를 헤더에, "구현 노트"를 소스에 넣습니다.

헤더 파일을 절대적으로 필요 이상으로 변경하지 않으려는 욕구와 관련하여-라이브러리가 "매우 많은 변화"에 있지 않은 경우 "인터페이스"와 "기능"이 크게 변경되지 않으며 헤더 주석이 너무 자주 변경되어야합니다. 반면, 소스 코드 주석은 소스 코드와 동기화 된 상태로 유지되어야합니다 ( "신선한").

doxygen 사용의 요점은 문서 를 생성 하고 다른 곳에서 액세스 할 수 있도록하는 것입니다. 이제 헤더의 모든 문서는 가비지이므로 필요한 함수 선언 및 과부하를 신속하게 발견하기가 더 어려워집니다. 하나의 라이너 의견이 최대가 될 수 있지만, 심지어 나쁜 습관입니다. 소스에서 문서를 변경하면 해당 소스를 다시 컴파일하고 다시 연결하십시오. 그러나 문서를 헤더에 넣으면 실제로 작은 부분을 변경하고 싶지 않으므로 프로젝트 재 구축의 상당 부분을 트리거하게됩니다.