주석을 달기 어려운 이유

코딩을 하면서 주석을 적절히 잘 달아야 한다는데는 이견이 없을 것이다. 하지만 현실은 주석이 제대로 달린 코드를 찾아보기 어렵다.

"주석이 제대로 달렸다"의 애매한 기준을 명확하게 정리해보면 다음과 같습니다.

• 과도한 주석은 나쁘다. 비용이 너무 많이 들어간다.
• 소스코드를 활용하고 유지보수하는데 어려움이 없어야 한다.
• 업데이트가 되어서 소스코드와 일치되어야 한다. 
• 전체적으로 일관된 표준을 지켜야 한다.  

주석하나 없이 깨끗한 소스코드나 있어도 소용없는 주석은 개발에 보통 어려움이 있는 것이 아니다. 약간의 시간을 투자해서 주석을 달게 되면 투자대비 몇배의 효과를 볼 수 있다.

그럼 가장 효과적으로 주석을 다는 방법에 대해서 알아보자.

회사의 주석 표준을 정한다.

Doxygen이나 Javadoc등의 표준 주석 Notation을 따르면 여러 툴의 많은 도움을 받을 수 있고 가독성이 높아진다. 신입사원이 들어와도 널리 알려진 표준이므로 쉽게 따라할 수 있게 된다.

주석은 소스코드보다 먼저다.

주석은 코딩하면서 짬짬히 다는 것이 아니다. 코딩 이전에 설계 시 Public function을 정의하면서 주석을 먼저 작성한다. 이렇게 설계를 해서 완벽할 때 구현(코딩)에 들어가면 된다.
코딩을 하면서 Public interface가 자주 바뀌면 주석도 바꾸기 매우 귀찮아지게 된다.
하위 설계는 코드와 주석을 적당히 이용하게 되면 문서로 작성할 필요가 없이 대부분 소스코드로 작성할 수 있다.

Public function 위주로 주석을 단다.

모든 소스코드에 주석을 달아야 한다고 하면 헬스클럽 1년 끊어 놓고 일주일 운동하고 포기하는 사태가 발생하게 된다. 당장 바쁜데 언제 시간을 내서 주석을 달 수 있겠는가? 
Public function은 다른 개발자들이 가장 빈번하게 참조를 해야 할 함수들이다. 같은 시간에 주석을 달아서 가장 효율성이 높다. 
하지만 모든 함수가 Public function이라면 효과도 없고 프로그램은 뒤죽박죽이 된다. 미리 Public function을 정하게 되면 최소화를 할 수 있다. 가능하면 거의 모든 함수를 속으로 숨기고 밖으로 최소한의 Interface만 open할 경우 프로그램도 간결하게 되고 유지보수도 쉬워진다. 
Doxygen이나 JavaDoc을 이용하면 API 메뉴얼이 근사하게 나오게 된다. 이 문서만 봐도 개발자들이 개발하는데 대단히 큰 도움을 준다.
이는 소스코드와 주석/설계문서를 지속적으로 일치 시키는데 지대한 도움을 준다.

주석같은 소스코드가 좋다.

복잡한 소스코드를 작성하고 주석으로 설명하는 것보다는 약간 효율이 떨어져도 가독성 높게 소스코드를 풀어서 쓰는 것이 좋다. 따라서 함수의 크기는 작게 유지하면서 읽어 내려가기 쉽게 작성하는 것이 좋다.
성능에 목숨거는 알고리즘을 개발하는 것이 아니라면 가독성 높은 소스코드를 작성하는 것을 높은 우선순위로 두는 것이 좋다. 왜냐하면 소스코드는 개발비보다 유지보수비가 몇배 더 들기 때문이다.

Prototyping 시에는 주석이 필요없다.

Prototyping한 소스코드는 버려야 한다. Prototype은 주석도 없고 에러처리도 안하고 가장 빠르게 검증을 해보는 것이다. 제품화 할 코드는 이것보다 몇배의 시간이 더 걸린다. 따라서 Prototyping을 한 소스코드는 꼭 버리고 제대로 설계를 해서 다시 만들어야 한다. 단, 참조는 가능하다.

처음에는 강제화가 필요하다.

강제화를 위해서는 리뷰가 필수이다. 코드 리뷰보다는 설계 리뷰가 중요하다. 설계 단계에서 대부분의 Public interface의 주석을 미리 완성하고 코딩에 들어가면 협업도 원활하고 재작업도 줄어든다. 그리고나서 코딩단계에서의 주석은 크게 강조하지 않아도 될 것이다.
규칙으로 무조건 주석을 달라고 강제하는 것보다는 정공법으로 분석/설계 리뷰를 통해서 설계가 끝났을 때 주석이 이미 달린 소스코드 헤더가 나오는 것이 좋다.


무조건 코딩부터 달려드는 것보다는 한번 더 생각해보고 Public interface를 먼저 정의하고 주석을 작성해서 리뷰하고 코딩을 하는 것이 전체 개발시간을 현저하게 단축 시켜준다. 시간이 없어서 주석도 없는 코딩만 마구 해대는 것은 핑계에 불과하다. 

효과적으로 주석을 다는 습관을 가지고 있다면 여러 동료들에게 사랑을 받고 후배들의 존경을 받을 것이다.