Doxygen을 활용한 주석 작성 스타일 가이드라인(규칙)

출처 : http://a.tk.co.kr/130

1. 개요

프로그램 소스 코드의 주석은 크게는 다른 사람이, 작게는 코드 작성자 자신이 소스 이해하는데 도움을 주고 오작동을 방지하며 수정을 쉽게 해주는 매우 중요한 역할을 합니다. 따라서 코딩 스타일과 마찬가지로 주석 역시 공통의 규격이 없다면 다른 사람의 주석을 읽는데 많은 수고가 필요하므로 규격화된 주석 작성방법이 필요합니다.

위와 같은 이유로 C++ 주석 스타일 가이드라인이 필요하며 적어도 팀 내에서는 동일한 주석 스타일을 사용할 필요성이 있습니다.

주석을 코드 라인단위로 너무 많이 작성하는 것은 오히려 코드를 보기 어렵게 하는 안 좋은 방법이지만 자신의 코딩스타일과 실력만을 믿고 주석을 전혀 쓰지 않는 행위는 더더욱 안 좋은 방법입니다. 많은 경험을 통하여 적절한 위치와 꼭 필요한 곳에 올바른 주석을 작성하는 것은 다른 사람을 위한 배려이자 자신의 실수를 줄이기 위한 매우 중요한 행동입니다.

과거에는 소스코드의 주석과 문서화를 별도로 행하였지만 개발자들이 문서작성을 꺼려하고 문서와 코드의 주석 모두 동기화시켜서 업데이트하기가 무척 번거롭기 때문에 대부분의 개발자들의 두 가지 방법 중 하나의 방법만 택하여 작업을 하는 것이 대부분입니다. 이러한 반복 작업을 간소화 하기 위해서 Doxygen 및 기타 소스코드 자동 문서화 도구를 사용하는 방법을 최근에는 많이 채택하고 있습니다.

(주의: 소스코드 자동 문서화 도구를 사용하여 주석을 작성한다고 하여 문서화를 하지 말라는 것은 절대 아닙니다. 설계나 구조 등의 요구사항 등에 대해서는 별도의 문서화가 작업이 되어야 합니다.)

Kyuseo 의 C++ 프로그래밍 주석 가이드라인은 Doxygen 방식을 기본 주석 작성 스타일로 가지고 있습니다.

2. RapidEngine에서 Doxygen 과 주석 스타일 가이드를 사용한 소스코드

3. RapidEngine에서 Doxygen과 주석 스타일 가이드를 사용하여 자동으로 문서화가 된 예

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

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

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

– 헤더파일(Header File)의 손상을 최소화한다.
(헤더파일은 개발자가 가장 자주 접근하는 파일이다. 무분별한 주석추가로 인하여 헤더파일 자체의 분석능력을 감소 시킨다면 개발자는 결국 불편한 문서파일만 접근하게 될 것이다.)

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

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

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

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

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

5. Doxygen을 활용한 주석 작성 규칙

– 소스 파일의 최상단에 파일명, 날짜, 제작자, 설명을 명기한다.
(주석의 방식이/**, */인 것에 주의한다. h, inl, cpp등 모든 소스파일에 표기한다.)

예)

/**
@file    RHttp.h
@date    2004/11/2
@author    채경석(kyuseo99@chol.com) RapidEngine™
@brief
*/

– 클래스 및 구조체 인터페이스 윗부분에 클래스 명, 날짜, 제작자, 설명 등을 첨부한다.
(주석의 방식이/**, */인 것에 주의한다.)

예)

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

– 클래스 / 구조체 멤버 변수 주석은 공백 1칸을 띄우고 “///<” 를 사용한다.

예)

long m_lFrameTic; ///< 1000/fps로 이 시간후 (ms) 프레임을 이동한다.

long m_lNewTime; ///< 최종 프레임 진행 시간

– 클레스 멤버 함수는 헤더에 “///<“을 사용하고 추가 설명, 리턴값 및 인자에 대한 필요하다면 구현부분에 추가 설명을 입력한다.

선언부 예)
DWORD* Decode( DWORD* pBuffer, DWORD* pSize ); ///< 암호화 버퍼와 변경된 size리턴 (4바이트 증가)

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

– 일반 함수는 헤더에 “///”을 사용하고 추가 설명, 리턴 값 및 인자에 대한 필요하다면 구현부분에 추가 설명을 입력한다.

선언부 예)
/// 하위폴더 포함하여 디렉토리를 생성한다.
extern BOOL CreateXDirectory( LPCTSTR szPath );

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