C++ 멤버 함수 주석은 .h에 아니면 .cpp에 작성해야 하나요?

rain의 이미지

Doxygen으로 source code를 돌리려구 합니다.
그런데 C++ 멤버 함수에 대한 주석 있잖습니까?


/**
 * WM_CREATE message handler.
 *
 * @brief 
 *
 * @param uMsg		This parameter identifies the message.
 * @param wParam 	This parameter is not used.
 * @param lParam 	Pointer to a CREATESTRUCT structure that contains 
 * 					information about the window being created.
 * @param bHandled	This This is a flag to indicate whether it handled 
 * 					the message.
 *
 * @return result	If a application this message, it should return 
 * 					zero to continue create of the window. If the
 * 					application return -1, the window is destroyed and
 * 					CreateWindowEx or CreateWindow function returns
 * 					a NULL handle.
 */
LRESULT CMainFrame::OnCreate(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled);

이거를 .h에 작성을 해주는게 좋나요 아니면 .cpp에 작성하는게 좋을까요?

Darkcircle의 이미지

rain wrote:
Doxygen으로 source code를 돌리려구 합니다.
그런데 C++ 멤버 함수에 대한 주석 있잖습니까?


/**
 * WM_CREATE message handler.
 *
 * @brief 
 *
 * @param uMsg		This parameter identifies the message.
 * @param wParam 	This parameter is not used.
 * @param lParam 	Pointer to a CREATESTRUCT structure that contains 
 * 					information about the window being created.
 * @param bHandled	This This is a flag to indicate whether it handled 
 * 					the message.
 *
 * @return result	If a application this message, it should return 
 * 					zero to continue create of the window. If the
 * 					application return -1, the window is destroyed and
 * 					CreateWindowEx or CreateWindow function returns
 * 					a NULL handle.
 */
LRESULT CMainFrame::OnCreate(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled);

이거를 .h에 작성을 해주는게 좋나요 아니면 .cpp에 작성하는게 좋을까요?

표준 라이브러리 헤더는 뜯어보셨죠?
고전적인 방법으로는 보통 function declaration 하면서
그 위에 혹은 오른쪽에 주석을 답니다.

뭐 꼭 그러라는 법은 없으니까 참고하세요 :D

---------------------------------------------------------------
폐인이 되자 (/ㅂ/)

Fe.head의 이미지

/**
 * @brief       WM_CREATE message handler.
 *

질문하고 별 상관은 없습니다만...

이게 좀 더 정확하지 않을까요?..

고작 블로킹 하나, 고작 25점 중에 1점, 고작 부활동
"만약 그 순간이 온다면 그때가 네가 배구에 빠지는 순간이야"

thisrule의 이미지

흔히 간단한 주석은 header에, 자세한 내용은 implementation할 때 하지 않나요?
개인적 취향이 강한 부분인거 같습니다.

sorcerer의 이미지

함수에 대한 대략적인 설명과 사용법 등은 헤더에 나오고, 함수의 구현에 대한 알고리즘 등등은 소스파일 내에 나와야 하지 않나요?
그래야 나중에 함수를 다른데서 사용하던가, 아니면 다른 사람이 사용 할 때 알 수 있지 않나요?
굳이 소스를 봐야 함수 설명이 나와있다면 그것도 재사용의 문제(귀차니즘발동ㅡ.,ㅡ; )를 낳을지도 모르고, 또한 헤더파일에서 함수 속이 뭐가 어찌 돌아간다라는 이야기는 할 필요가 없는게 아닐까 합니다.

뭐, 정리하면
헤더파일 : 함수가 하는 일, 반환값, 인자 에 대한 설명
소스파일 : 함수가 결과를 내기위해 돌아가는 과정 중 설명이 필요한 부분.
정도 될 듯 하네요.

SOrCErEr

bugiii의 이미지

sorcerer wrote:
함수에 대한 대략적인 설명과 사용법 등은 헤더에 나오고, 함수의 구현에 대한 알고리즘 등등은 소스파일 내에 나와야 하지 않나요?
그래야 나중에 함수를 다른데서 사용하던가, 아니면 다른 사람이 사용 할 때 알 수 있지 않나요?
굳이 소스를 봐야 함수 설명이 나와있다면 그것도 재사용의 문제(귀차니즘발동ㅡ.,ㅡ; )를 낳을지도 모르고, 또한 헤더파일에서 함수 속이 뭐가 어찌 돌아간다라는 이야기는 할 필요가 없는게 아닐까 합니다.

뭐, 정리하면
헤더파일 : 함수가 하는 일, 반환값, 인자 에 대한 설명
소스파일 : 함수가 결과를 내기위해 돌아가는 과정 중 설명이 필요한 부분.
정도 될 듯 하네요.

라이브러리를 사용하는 사람의 입장에서는 그럴 수도 있습니다. 하지만, 라이브러리를 만드는 사람의 경우는 어떨까요? 만약 구현 내용의 변경이나 리턴값 변경이 있다면 해당 헤더 파일을 다시 열어서 그에 맞는 내용으로 수정해야 할텐데요. 번거로운 경우가 많습니다.

저같은 경우에는 헤더는 정말 필요한 경우가 아니면 혹은 헤더에만 있는 것 (매크로나 상수 등) 만을 문서화하고 클래스 자체의 문서까지 정도만 헤더에 둡니다.

나머지 멤버들의 주석은 구현쪽에 놓고 실제 라이브러리를 사용하고 참조하는 사람들을 위해서 헤더를 보라고 하는 것이 아니라 doxygen 출력물을 보거나 아예 소스 자체를 보도록 하는 것이 낫다고 생각했습니다.

결국 구현할 때 거추장스러워서 (귀찮아서) 그렇게 했다는 것이라, 별로 공감을 얻을 수는 없을 것 같긴합니다만... -_-;

댓글 달기

Filtered HTML

  • 텍스트에 BBCode 태그를 사용할 수 있습니다. URL은 자동으로 링크 됩니다.
  • 사용할 수 있는 HTML 태그: <p><div><span><br><a><em><strong><del><ins><b><i><u><s><pre><code><cite><blockquote><ul><ol><li><dl><dt><dd><table><tr><td><th><thead><tbody><h1><h2><h3><h4><h5><h6><img><embed><object><param><hr>
  • 다음 태그를 이용하여 소스 코드 구문 강조를 할 수 있습니다: <code>, <blockcode>, <apache>, <applescript>, <autoconf>, <awk>, <bash>, <c>, <cpp>, <css>, <diff>, <drupal5>, <drupal6>, <gdb>, <html>, <html5>, <java>, <javascript>, <ldif>, <lua>, <make>, <mysql>, <perl>, <perl6>, <php>, <pgsql>, <proftpd>, <python>, <reg>, <spec>, <ruby>. 지원하는 태그 형식: <foo>, [foo].
  • web 주소와/이메일 주소를 클릭할 수 있는 링크로 자동으로 바꿉니다.

BBCode

  • 텍스트에 BBCode 태그를 사용할 수 있습니다. URL은 자동으로 링크 됩니다.
  • 다음 태그를 이용하여 소스 코드 구문 강조를 할 수 있습니다: <code>, <blockcode>, <apache>, <applescript>, <autoconf>, <awk>, <bash>, <c>, <cpp>, <css>, <diff>, <drupal5>, <drupal6>, <gdb>, <html>, <html5>, <java>, <javascript>, <ldif>, <lua>, <make>, <mysql>, <perl>, <perl6>, <php>, <pgsql>, <proftpd>, <python>, <reg>, <spec>, <ruby>. 지원하는 태그 형식: <foo>, [foo].
  • 사용할 수 있는 HTML 태그: <p><div><span><br><a><em><strong><del><ins><b><i><u><s><pre><code><cite><blockquote><ul><ol><li><dl><dt><dd><table><tr><td><th><thead><tbody><h1><h2><h3><h4><h5><h6><img><embed><object><param>
  • web 주소와/이메일 주소를 클릭할 수 있는 링크로 자동으로 바꿉니다.

Textile

  • 다음 태그를 이용하여 소스 코드 구문 강조를 할 수 있습니다: <code>, <blockcode>, <apache>, <applescript>, <autoconf>, <awk>, <bash>, <c>, <cpp>, <css>, <diff>, <drupal5>, <drupal6>, <gdb>, <html>, <html5>, <java>, <javascript>, <ldif>, <lua>, <make>, <mysql>, <perl>, <perl6>, <php>, <pgsql>, <proftpd>, <python>, <reg>, <spec>, <ruby>. 지원하는 태그 형식: <foo>, [foo].
  • You can use Textile markup to format text.
  • 사용할 수 있는 HTML 태그: <p><div><span><br><a><em><strong><del><ins><b><i><u><s><pre><code><cite><blockquote><ul><ol><li><dl><dt><dd><table><tr><td><th><thead><tbody><h1><h2><h3><h4><h5><h6><img><embed><object><param><hr>

Markdown

  • 다음 태그를 이용하여 소스 코드 구문 강조를 할 수 있습니다: <code>, <blockcode>, <apache>, <applescript>, <autoconf>, <awk>, <bash>, <c>, <cpp>, <css>, <diff>, <drupal5>, <drupal6>, <gdb>, <html>, <html5>, <java>, <javascript>, <ldif>, <lua>, <make>, <mysql>, <perl>, <perl6>, <php>, <pgsql>, <proftpd>, <python>, <reg>, <spec>, <ruby>. 지원하는 태그 형식: <foo>, [foo].
  • Quick Tips:
    • Two or more spaces at a line's end = Line break
    • Double returns = Paragraph
    • *Single asterisks* or _single underscores_ = Emphasis
    • **Double** or __double__ = Strong
    • This is [a link](http://the.link.example.com "The optional title text")
    For complete details on the Markdown syntax, see the Markdown documentation and Markdown Extra documentation for tables, footnotes, and more.
  • web 주소와/이메일 주소를 클릭할 수 있는 링크로 자동으로 바꿉니다.
  • 사용할 수 있는 HTML 태그: <p><div><span><br><a><em><strong><del><ins><b><i><u><s><pre><code><cite><blockquote><ul><ol><li><dl><dt><dd><table><tr><td><th><thead><tbody><h1><h2><h3><h4><h5><h6><img><embed><object><param><hr>

Plain text

  • HTML 태그를 사용할 수 없습니다.
  • web 주소와/이메일 주소를 클릭할 수 있는 링크로 자동으로 바꿉니다.
  • 줄과 단락은 자동으로 분리됩니다.
댓글 첨부 파일
이 댓글에 이미지나 파일을 업로드 합니다.
파일 크기는 8 MB보다 작아야 합니다.
허용할 파일 형식: txt pdf doc xls gif jpg jpeg mp3 png rar zip.
CAPTCHA
이것은 자동으로 스팸을 올리는 것을 막기 위해서 제공됩니다.