[Doxygen] 주석의 기본 원칙

1          기본 원칙

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

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

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

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

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

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

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

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

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

          지킬 필요는 없다.