7월 13일에 조운영씨와 메신저로 이런저런 대화를 나눴다. 대부분의 대화는 T-SQL에 관한 질문과 답변이었지만 다른 이야기도 오갔다. (사실 거의 혼자 떠들었다.) 주석달기에 관한 이야기는 운영씨가 재훈씨는 혹시 소스에 주석을 다는거에 대해서 어떻게 생각하시는지요? 견해라 할까?
라는 질문을 하면서 시작됐다. 메신저로 오간 대화체를 그대로 실을 생각은 없으니 내용을 다시 정리해봤다.
문서화 도구
소스코드에 주석을 다는 일을 당연하게 받아들이기도 하지만, 사실 그것으로 끝나버리면 투자한 시간이 아깝다. 주석을 추가한 후에 별도의 클래스 명세서를 작성하는 경우도 있는데, 이 두 가지를 한번에 낚기 위해서 문서 자동화 도구를 활용한다. 프로그래밍 언어에 따라 Doxygen, NDoc, Javadoc 등을 사용하는데, 사용법이 유사해서 추가적인 오버헤드는 거의 없다.
접근 제한
문서화 도구는 기본적으로 public/protected 클래스 및 메써드에 대해 주석을 달도록 권장하고 있다. 해당 구성요소에 주석이 없거나 일부 매개변수에 대한 설명이 빠져 있거나 하면 경고 또는 오류를 반환한다. 문서화 도구를 경험하지 못한 사람은 이러한 기능이 아무것도 아닌 듯 생각할 수도 있다. 그러나 내 경험은 다른 말을 전한다.
객체지향개발이라는게 이제는 화두가 될 수 있는지 조차 의심스럽지만, 의외로 객체지향을 이해하는 개발자가 많지 않은 것도 사실이다. 이해할만 하면 관리직으로 진출하게 되니 숙련된 개발자가 많지 않다. 그래서 2년 전의 나 같은 초급 개발자의 비중이 크기 마련이다. 객체지향개발에 익숙하지 못한 프로그래머는 클래스를 만들면 객체지향개발인 줄 착각한다. 지나치게 냉소적이었던 것 같은데, 사실 그렇게 교육 받았으니 그럴 만도 하다.
이들이 저지르는 또다른 실수는 클래스든 메써드든 public으로 선언해버린다는 점이다. 접근제한이라는 문제를 고려하지 않는다. 경험이 없는 개발자에겐 어떤 메써드를 public, protected, 또는 private으로 선언할 것인지 결정하는 것이 결코 쉽지 않다. 그렇게 한참 고민하고 나면 에라, 모르겠다. 그냥 전부 공개해버리자.
라는 생각이 들게 마련이다.
문서 자동화 도구로 주석을 달게 될 쯤엔 이 문제에 대해 한번 더 고민하게 된다. 공개된 메써드가 많을수록 귀찮은 작업을 더 해야 한다. 당연하게도 이 메써드를 정말 공개할 필요가 있나?
라고 재고하게 된다. 또한 여러 개의 공개된 메써드를 호출해야 하는 경우에는 인터페이스를 조금 더 간단하게 만들어서 공개된 메써드의 개수를 줄일 수는 없을까?
라는 고민도 하게 된다.
코드가 주석이다.
주석을 달아야 하는 상황이라도 어느 정도 수준을 요구하는지는 상황에 따라 다르다. 장황하게 이것저것 늘어놓는 주석은 보는이를 피곤하게 하지만, 동시에 작성자도 귀찮게 한다. 리팩토링이나 디자인패턴을 통해서 주석의 양을 줄일 수 있다. 기능이 무엇인지 도무지 알아볼 수 없는 DoWhatHaveToBeDone 메써드가 있다고 치자. 이때 rename 리팩토링을 해서 메써드의 이름을 ChangeCustomerName으로 바꾼다면, 주석으로 설명해야 하는 내용을 줄일 수 있다. 이런 식으로 문서화 도구는 개발자의 행동 양식을 제어하고, 보다 나은 Practices을 익히도록 도와준다.
Update 2006.07.24 겐도형의 말(주석은 쓸모 없는 것, 주석은 쓸모 없는 것 2)마따나 API 개발하는게 아니면, 주석이 필요 없도록 제대로 디자인하는게 중요하다. 그래도 주석이나 문서를 만들라는 외부의 압력이 있다면 문서화 도구를 사용하는 것이 편할테고 위에서 나열한 장점도 경험해 볼 수 있다. 경험이 부족한 개발자에게 반성의 기회를 제공할 수 있다는 점도 빼먹을 수 없다.
주석은 쓸모없는 것 2
"주석은 쓸모 없는 것" http://process.kaist.ac.kr/~gendoh/blog/18 이란 글을 작년에 썼는데 https://andromedarabbit.net/benefits_of_documatation_tools/ 글을 또 발견하게 되서 좀더 보충. OOPL(Object-Oriented Programming Language)들이 Method 혹은 포괄적인 의미의 Property(최근 언어들은 Member f..