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

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

1. 개요

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

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

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

문서화를 자동으로 XML 문서 주석

[ 서우석 2005/11/22]

여러분은 얼마나 많은 주석을 작성합니까? 그리고 주석을 어떤 용도로 사용하십니까? 주석을 작성해야 하는지, 또는 말아야 하는지에 대한 논의는 상당히 오랜 시간 동안 지속되어 왔으면서도 여전히 결론이 내려질 가능성이 그렇게 많지 않아 보이다. 그 옛날 소크라테스가 제자들에게 주석을 작성하는 것이 옳은가에 대한 질문을 했을 때, 한 제자는 코드의 유지 보수 측면에서 반드시 필요하다고 주장하고, 또 다른 제자는 코드가 모든 것을 말할 수 있어야 한다고 주장한다.

개인적으로는 매우 어려운 알고리즘이 아닌 이상 주석을 작성할 필요가 거의 없으며, 주석을 작성해야 할 만큼 복잡한 모듈은 리팩토링을 통해서 스스로를 설명할 수 있는(Self-Document) 보다 작은 모듈로 나누어져야 한다고 생각한다. 지금까지 이러한 논의가 끊이지