C 또는 C++에서 함수를 문서화하는 위치는 어디입니까?
는 여러의 파일이 C 있기 를 들어, 나는여개파의있일 C프그을있가, 서예들어, 를는나래다, 그러램고지, 이는로들▁with,stuff.c기능을 하고, 몇가지구현고하기을능,,stuff.h기능 프로토타입을 사용합니다.
기능을 댓글로 어떻게 문서화해야 합니까?
파일에 , 더파일있모문서든, 문를가있합니다어야에 있는 ..c파일 또는 둘 다에 대한 문서를 복제합니까?저는 후자의 접근 방식을 좋아하지만, 다른 것이 아닌 하나의 문서를 업데이트하는 문제에 직면하게 됩니다(일반적으로 헤더 파일을 먼저 수정하는 경우). 헤더 파일을 먼저 수정하면 해당 주석이 반영되지만, 구현을 업데이트하면 해당 주석만 변경됩니다.
이 질문과 답변은 C++ 코드에도 적용됩니다. 참고 항목설명을 어디에 넣어야 합니까?
기능을 사용하는 사람들이 알아야 할 정보를 헤더에 넣습니다.
기능 유지 관리자가 알아야 할 정보를 소스 코드에 넣습니다.
나는 구글 C++ 스타일 가이드를 따르는 것을 좋아합니다.
그건 다음과 같습니다.
함수 선언
- 모든 함수 선언에는 함수의 기능과 사용 방법을 설명하는 주석이 바로 앞에 있어야 합니다.이러한 주석은 명령형("파일 열기")이 아니라 설명형("파일 열기")이어야 합니다. 주석은 함수를 설명하며, 함수가 수행할 작업을 지시하지 않습니다.일반적으로 이러한 주석은 함수가 작업을 수행하는 방법을 설명하지 않습니다.대신, 이는 함수 정의의 주석에 맡겨야 합니다.
함수 정의
각 함수 정의에는 함수가 수행하는 작업과 함수가 수행하는 작업에 대해 설명하는 주석이 있어야 합니다.예를 들어, 정의 주석에서 사용하는 코딩 방법을 설명하거나, 단계의 개요를 제공하거나, 실행 가능한 대안을 사용하지 않고 기능을 수행한 방식으로 구현하기로 선택한 이유를 설명할 수 있습니다.예를 들어, 함수의 전반부에 대해 잠금을 획득해야 하는 이유와 후반부에 대해 잠금이 필요하지 않은 이유를 언급할 수 있습니다.
함수 선언과 함께 제공된 설명을 .h 파일이나 다른 곳에서 반복해서는 안 됩니다.기능이 수행하는 작업을 간략하게 요약하는 것은 괜찮지만, 코멘트의 초점은 기능이 수행하는 방식에 맞춰져야 합니다.
문서가 소스 코드의 특수하게 조작된 주석에 의해 생성되도록 doxygen과 같은 도구를 사용해야 합니다.
저는 이것에 대해 왔다 갔다 했고 결국 헤더 파일의 문서화를 결정했습니다.C/C++ API의 대부분은 원본 헤더 파일에 액세스할 수 있으므로 [1] 내에 있는 모든 주석에 액세스할 수 있습니다.여기에 댓글을 달면 개발자가 댓글을 볼 수 있는 기회가 극대화됩니다.
하지만 헤더 파일과 소스 파일 간에 주석이 중복되는 것을 피합니다(그냥 낭비처럼 느껴집니다).Vim을 사용할 때는 정말 짜증이 나지만 대부분의 IDE는 헤더 파일 주석을 선택하여 인텔리센스나 매개 변수 도움말과 같은 것에 넣을 것입니다.
이 규칙의 예외에는 특정 COM 라이브러리에서 생성된 헤더 파일이 포함됩니다.
이는 종종 코딩 표준으로 설정된 내용에 따라 달라집니다.많은 사람들이 문서를 .h 파일에 넣고 구현을 .c 파일에 남기는 것을 선호합니다.코드가 완성된 많은 IDE도 .c 파일의 문서보다 이 문제를 더 쉽게 이해할 수 있습니다.
하지만 .h 파일에 문서를 넣는 것의 주요 포인트는 다른 프로그램과 공유할 라이브러리나 어셈블리를 작성하는 것이라고 생각합니다.배포할 구성 요소가 포함된 .dll(또는 .so)을 작성하고 있다고 가정합니다.다른 프로그래머들은 당신의 .h를 포함할 것이지만, 그들은 종종 그 뒤에 구현 파일을 가지고 있지 않을 것입니다.이 경우 .h 파일의 설명서는 매우 유용합니다.
같은 프로그램에서 사용할 클래스를 작성할 때도 마찬가지입니다.다른 프로그래머와 함께 작업하는 경우 대부분의 프로그래머는 코드가 구현되는 방법보다는 코드와 상호 작용하는 방법을 위해 헤더 파일을 봅니다.구현 방법은 구성 요소를 사용할 사람이나 코드의 문제가 아닙니다.다시 한 번, 헤더에 있는 문서는 그 사람이나 그 사람들이 그 코드를 사용하는 방법을 알아내는 데 도움이 될 것입니다.
사람들이 머리글과 컴파일된 구현 버전만 가지고 있을 때 이러한 기능을 사용할 수 있다는 점을 고려하십시오.기능을 사용하는 데 필요한 모든 사항이 머리글에 기록되어 있는지 확인합니다.구현 세부 정보는 소스에서 문서화할 수 있습니다.
헤더와 구현 파일의 주석은 두 가지가 사용되는 방식의 차이를 반영해야 합니다.
분명히 헤더에 속하는 인터페이스 문서(예: JavaDocs와 동일한 일반 순서로 Doxygen으로 추출)를 작성하려는 경우.별도의 문서를 작성하기 위해 주석을 추출하지 않더라도 동일한 일반적인 아이디어가 적용됩니다. 주로 헤더에 속하거나 독점적으로 코드를 사용하는 인터페이스/방법을 설명하는 주석입니다.
구현의 주석은 일반적으로 구현과 관련되어야 합니다.빈번한 연습과는 반대로, 일이 어떻게 돌아가는지 설명하려고 하기보다는, 대부분은 왜 특정한 결정이 내려졌는지 설명해야 합니다.이는 특히 타당한 결정을 내릴 때 해당되지만, 그러한 결정이 명확하지 않을 수도 있습니다(예: 안정적인 정렬이 필요하기 때문에 Quicksort를 사용하지 않았다는 점에 주목).
생각해보면 정말 간단합니다.
API 문서는 반드시 헤더 파일에 들어가야 합니다.외부 인터페이스를 정의하는 헤더 파일이기 때문에 API 문서가 이동합니다.
원칙적으로 구현 세부 정보는 API 사용자에게 숨겨야 합니다.여기에는 구현 문서가 포함됩니다(시간 복잡성 등과 같이 사용에 영향을 미칠 수 있는 경우는 제외).따라서 구현 문서는 구현 파일에 포함되어야 합니다.
여러 장소에서 문서를 복제하지 마십시오.유지 관리할 수 없으며 누군가 변경해야 하는 즉시 동기화되지 않습니다.
함수 선언이 없는 템플릿 헤더 파일과 주석이 달린 소스 코드 파일을 입력하는 간단한 스크립트를 작성했습니다.이 스크립트는 함수 정의 앞에 있는 주석을 소스 코드 파일에서 추출하고 이 주석과 관련 함수 선언을 출력 헤더 파일에 씁니다.이렇게 하면 1) 함수 주석을 작성해야 하는 곳이 하나뿐이며, 2) 헤더 파일의 문서와 소스 코드 파일이 항상 동기화된 상태로 유지됩니다.함수 구현에 대한 주석은 함수 본문에 포함되며 추출되지 않습니다.
문서를 한 곳에 보관하여 유지 관리의 악몽을 방지하십시오.개인적으로 두 복사본을 동시에 보관할 정도로 까다로울 수 있지만 다음 사용자는 그렇지 않습니다.
doxygen과 같은 것을 사용하여 문서의 "예쁜" 버전을 만듭니다.
언급URL : https://stackoverflow.com/questions/3568052/where-to-document-functions-in-c-or-c
'programing' 카테고리의 다른 글
| WooCommercommercommerce:체크아웃 페이지에서 기본적으로 국가 설정 (0) | 2023.06.13 |
|---|---|
| 장고: 외부 키 충돌에 대한 역방향 접근기 (0) | 2023.06.13 |
| Pandas Dataframe에서 dtype을 객체로 사용하는 열을 문자열로 변환하는 방법 (0) | 2023.06.13 |
| Android 에뮬레이터에 텍스트 붙여넣기 (0) | 2023.06.13 |
| IIS 구성 오류 - 이 구성 섹션은 이 경로에서 사용할 수 없습니다. (0) | 2023.06.13 |