코드를 수정하면서 이전에 있던 주석을 그냥 놔두면, 유지 보수 담당자는 혼란을 일으키게 된다. 자신이 이해한 코드와 주석이 다르기 때문이다. 그러므로 코드를 수정할 때, 주석 내용이 맞지 않는다면 반드시 즉석에서 고쳐라. 이전 주석을 건드리기 싫다면, 아래에다 꼬릿말 형식으로라도...
2 "어떻게"보다는 "왜"를 기술하자.
코드가 어떤 기능을 하는지를 안다면, 수정이나 디버깅이 훨씬 쉽다. 까다로운 API들을 사용하는 함수가 있을 때, 그 API 사용법 같은 것을 적기 보다는, 그 함수 자체가 API들을 사용해서 무엇을 하려하는지를 주석으로 달라는 말이다.
3 뻔한 주석은 달지 말자.
"i에다 1을 더한다"와 같은 식의 주석은 차라리 달지 않는 것이 낫다. 이런 주석 달 시간 있으면, 클래스나 함수의 전반적인 목적 같은 것이나 주석으로 기술하라.
4 주석 포맷을 만들었다면, 모든 항목을 채워 넣자.
DoxyGen 같은 툴을 사용하기로 협의가 되어서, 주석 포맷을 정했다면 필요한 항목들을 채워넣어야 한다. 그냥 필드만 매크로 같은 걸로 만들어넣고, 내용을 비워놓는다면 주석을 달지 않은 것과 같다. 이래놓고 라인수 운운하면 욕 먹는다.
5 디자인 문서는 개략적으로 만들자.
디자인 문서는 코드가 아니다. 너무 자세하게 만드는 것은 시간과 노력의 낭비다. 구현 위주보다는 목적과 흐름 위주로 만들어라. 실제 자세한 설명은 코드에다 달아라.
6 단위를 표기하자.
미터나, 킬로그램 같이 실세계에서 의미가 있는 값이라면, 그것에 대한 주석을 달아라. 코드를 이해하는 데 좀 더 도움이 된다.
7 문제를 발견했다면, 코드에다 그것을 적어놓자.
"이건 아닌 것 같은데... 하지만 내가 제대로 이해한 건지 모르겠네." 같은 코드를 봤다면, 그것을 코드에다 기술해 둬라. 잘 모르는 상태에서 무조건 수정하는 것도 잘못이겠지만, 그렇다고 그냥 넘어가버리면 잊어버리게 된다. 혹시 그것이 진짜 버그였다면, 수정하는 데 많은 도움이 된다.
Visual C++ 같은 경우에는 pragma message 같은 걸 이용해도 좋다.
8 변수에도 주석을 달자.
클래스나 함수 뿐 아니라, 변수에도 주석을 달아야 한다. (변수가 가져야할 일반적인 값, 단위 등... 변수의 이름도 일종의 주석이다!) 특히나 지역 변수를 많이 사용하는 코드라면 더욱 주석을 달아야 한다. 어떤 변수가 어떤 의미를 가지는지 모르면, 그 변수들을 사용하는 코드를 보면서 용도를 추측해야 하는데, 이는 짜증나는 작업이다.
Visual C++ 같은 경우에는 pragma message 같은 걸 이용해도 좋다. 