[coding] Doxygen 형식 - 주석

1 기본 원칙

1.1 주석작성의 목적은 자기 자신뿐만이 아니라 다른 사람들을 위한 작업이다.
(따라서 자기만 알아볼 수 잇는 약어를 사용하거나 농담으로 주석을 작성하면 안된다.)

1.2 주석은 모국어로 기입한다.
(아무리 타국어를 잘하는 사람이라도 모국어보다 타국어를 잘할 수 없다. 또한 다른 사람들을 위한 배려이다.)

1.3 주석은 항상 최신으로 유지가 되어야한다.
(코드를 변경한 이후에는 반드시 관련 주석을 함께 변경해야한다. 최신이 아닌 주석은 오히려 코드 분석에 큰 방해가 된다.)

1.4 헤더파일의 손상을 최소화한다.
(헤더파일은 개발자가 가장 자주 접근하는 파일이다. 무분별한 여러라인의 주석추가로 인하여 헤더파일 자체의 분석능력을 떨어뜨리다면 개발자는 결국 열기 불편한 문서파일만 접근하게 될것이다.)

1.5 중복된 주석 입력 작업은 최소화 한다.
(함수의 인자를 설명하기 위해서 그 인자를 중복해서 입력할 필요는 없다. 동일한 클레스 멤버 함수의 설명주석을 헤더와 구현 파일에 중복하여 기입 할 필요가 없다. 불필요한 중복된 주석입력 작업은 주석입력을 꺼리게 만드는 계기가 된다. 단 클래스와 같이 중요도가 매우 높은 항목은 예외로 한다.)

1.6 Doxygen은 파일, 클래스, 구조체, 멤버변수, 멤버함수, 일반함수등에만 사용한다.
(Doxygen의 모든 문법과 방법을 사용하여 너무 많은 활용을 하는 것은 오히려 코드가 보기 좋지 않고 가독성이 떨어지게 된다.)

1.7 함수의 주석은 동사로 끝을 맺고 변수나 인자, 객체의 주석은 명사로 끝을 맺는다.
(함수는 행위를 나타내고 변수는 객체를 나타내기 때문이다.)

1.8 무분별한 주석추가는 자제한다.
(아주 어려운 알고리즘이 아니라면 라인단위로 주석을 다는 것은 코드의 가독성을 해치게 된다.)

1.9 주석 입력작업의 목적은 코드를 알아보기 좋게 하는 작업이므로 모든 사항을 지나치게 철저하게

지킬 필요는 없다.

2 Doxygen 형식

2.1 소스 파일의 최상단에 파일명, 날짜, 제작자, 설명등을 명기한다.
(주석의 방식이/**, */인것에 주의한다. h, inl, cpp등 모든 소스파일에 표기한다.)
예)
/**
@file RHttp.h
@date 2004/11/2
@author 개똥이

            RapidEngine™
@brief
*/

2.2 클래스 및 구조체 인터페이스 윗부분에 클래스명, 날짜, 제작자, 설명등을 첨부한다.
(주석의 방식이/**, */인것에 주의한다.)
예)
/**
@class CRHttp
@date 2004/11/2
@author 개똥이

@brief Http 클라이언트
@warning 몇몇 서버상의 오류로 가능한 업로드는 소문자로 한다. (특히 하나포스 마이홈)
*/
class CRHttp
{
…
};

2.3 클래스 / 구조체 멤버 변수 주석은 공백 1칸을 띄우고 “///<” 를 사용한다.
예)
long m_lFrameTic; ///< 1000/fps로 이시간후 (ms) 프레임을 이동한다.
long m_lNewTime; ///< 최종 프레임 진행 시간

2.4 클레스 멤버 함수는 헤더에 “///<”을 사용하고 추가 설명, 리턴값 및 인자에 대한 필요하다면 구현부분에 추가 설명을 입력한다.
선언부 예)
DWORD* Decode( DWORD* pBuffer, DWORD* pSize ); ///< 암호화 버퍼와 변경된 size리턴 (4바이트 증가)

구현부 예)
/**
@return 찾은 그룹 (없으면 NULL)
@warning 외부에서 관련된 동기화 객체를 Lock을 걸어 사용한다.
*/
CRGroup* CRServer::FindGroup( RGID gid ///< 그룹 아이디
)
{
}

2.5 일반 함수는 헤더에 “///”을 사용하고 추가 설명, 리턴값 및 인자에 대한 필요하다면 구현부분에 추가 설명을 입력한다.
선언부 예)
/// 하위폴더 포함하여 디렉토리를 생성한다.
extern BOOL CreateXDirectory( LPCTSTR szPath );

구현부 예)
/**
@return 디렉토리 생성 성공유무
@warning King\kong\file.dat와 같은 파일명은 포함 안된다.
*/
BOOL CreateXDirectory( LPCTSTR szPath ///< 생성할 디렉토리명 (예:C:\\King\\kong, King\\kong\\)
)
{
}

3 일반 형식

3.1 주석은 설명하는 구문의 앞 라인에 작성한다.
올바른 예)
// 파일의 크기가 설정되지 않았다면…
if( nSize == 0 )
{
return FALSE;
}

잘못된 예)
if( nSize == 0 ) // 파일의 크기가 설정되지 않았다면…
{
return FALSE;
}

if( nSize == 0 )
{ // 파일의 크기가 설정되지 않았다면…
return FALSE;
}

[출처] http://blog.naver.com/kw1128?Redirect=Log&logNo=70003380233|작성자 훨훨