C/C ++ 헤더 파일 문서 [폐쇄

StackOverflow https://stackoverflow.com/questions/487114

  •  20-08-2019
  •  | 
  •  

문제

C ++에서 공개 헤더 파일을 만들 때 모범 사례는 무엇이라고 생각하십니까?

  1. 헤더 파일에 없음, 간단하거나 대규모 문서가 포함되어야합니까? 문서가 거의없는 것 (일부 외부 문서에 의존)에서 불일한, 유효한 매개 변수, 반환 값 등의 대규모 사양에 이르기까지 모든 것을 보았습니다. 정확히 무엇을 선호하는지 확실하지 않습니다. 반면에 편집자의 경우 매우 간단한 문서가있는 헤더 파일은 종종 한 또는 두 페이지의 텍스트에 전체 인터페이스를 표시 할 수 있습니다.

  2. 간단하거나 거대한 문서와 같은 것을 가지고 있다고 가정 해 봅시다. 나는 반환 값, 매개 변수 등을 문서화하는 Javadoc과 비슷한 것을 원한다. C ++의 가장 좋은 컨벤션은 무엇입니까? 내가 기억할 수있는 한, doxygen은 Java Doc 스타일 문서로 좋은 일을하지만,이를위한 다른 규칙과 도구가 있습니까?

도움이 되었습니까?

해결책

일반적으로 인터페이스에 대한 문서를 넣습니다 (매개 변수, 반환 값, 무엇 함수는 인터페이스 파일 (.h)에 있고 구현에 대한 문서 (어떻게 함수는 구현 파일 (.c, .cpp, .m)에서입니다.

선언 직전에 수업에 대한 개요를 작성하므로 독자에게는 즉각적인 기본 정보가 있습니다.

내가 사용하는 도구는 Doxygen입니다.

다른 팁

  1. 헤더 파일 자체에 문서가 있습니다. 별도의 문서가 아닌 코드 옆에 정보를 갖도록 디버깅을 크게 향상시킵니다. 일반적으로 코드 옆에 API (반환 값, 인수, 상태 변경 등)를 문서화하고 별도의 문서에서 고급 아키텍처 개요를 문서화합니다 (모든 것이 어떻게 구성되는지에 대한 광범위한 견해를 제공하기 위해; 일반적으로 여러 클래스를 한 번에 참조하기 때문에 코드와 함께 배치하기가 어렵습니다).

  2. Doxygen은 내 경험에서 괜찮습니다.

나는 Doxygen이 문서를 생성하기위한 가장 일반적인 플랫폼이라고 생각하며, 내가 아는 한, Javadoc-Notation (물론에 국한되지 않음)을 다룰 수 있습니다. 나는 c에 doxygen을 사용했는데, 결과는 OK 결과를 가지고 C ++에 더 적합하다고 생각합니다. Oc

문서의 양과 관련하여, 나는 문서화가 된 적이 없지만, 내가 좋아하든 아니든, 더 많은 문서를 갖는 것은 항상 문서화가없는 것입니다. API 다 문서를 헤더 파일에 넣고 구현에 구현 문서를 넣었습니다 (이성에 맞지 않습니까?). :) 그런 식으로, Ides는자가 완성 중에 그것을 집어 들고 보여줄 기회가 있습니다 (예 : javadocs, 예를 들어 Doxygen을 위해이를 수행하십시오). Javadoc은 첫 번째 문장 (예 : 첫 번째 전체 정지까지)을 간단한 설명으로 사용한다는이 추가적인 기발한 점을 가지고 있습니다. Doxygen 이이 작업을 수행하는지 모르지만 문서를 작성할 때는 고려해야합니다.

많은 문서화가 있으면 날짜가 오래 걸릴 위험이 있지만 문서를 코드에 가깝게 유지하면 사람들이 최신 상태를 유지할 수있는 기회를 제공하므로 소스/헤더 파일에 확실히 보관해야합니다. 그래도 잊혀지지 말아야 할 것은 문서 제작입니다. 예, 어떤 사람들은 문서를 직접 사용하거나 (IDE 또는 무엇이든 또는 헤더 파일을 읽는 것만으로도 다른 방법을 선호하므로 일부 사람들은 온라인으로 온라인으로 업데이트 된 API 문서를 모두 사용하는 것을 고려해야합니다. 닉스 기반 개발자를 대상으로하는 경우 Man-Files를 생산할 수도 있습니다.

그것은 내 두 센트입니다.

코드에 혼자있을 수있는 코드에 충분히 넣으십시오. 문서가 별도의 위치에 있던 거의 모든 프로젝트, 날짜가 오래되었거나 완료되지 않았습니다. 부분적으로 별도의 문서 인 경우 별도의 작업이되면 부분적으로 경영진이 작업으로 허용하지 않았기 때문에. 예산. 흐름의 일부로 인라인을 문서화하는 것은 내 경험에서 훨씬 더 잘 작동합니다.

대부분의 편집자가 인식하는 형식으로 문서를 작성하십시오. C ++의 경우 이것은 //보다는 /* 인 것 같습니다. 그렇게하면 접어서 선언을 볼 수 있습니다.

어쩌면 당신은 관심이있을 것입니다 GTK-DOC. "설정 및 사용이 약간 어색 할 수 있지만"소스 코드에서 멋진 API 문서를 얻을 수 있습니다.

문자열 유틸리티 기능

라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top