주석에 대한 고민

코드 주석은 필수인가?

친구가 흥미로운 주제를 던져주었다. Software engineering, Agile 관련 도서들을 읽고 지금까지 개발하며 들었던 의문이지만 글로 작성하면서 의식의 흐름대로 생각을 정리해보려고 한다.

찬성, 반대 진영 의견을 들어보면 모두 각자의 입장에서 일리 있는 이야기다.

찬성파

독자(작성자 본인을 포함해서 추후에 코드를 보게 될 사람들)에게 코드만 보아서는 알 수 없는 정보들과 수정 이력을 공유하고, 코드를 빠르게 파악할 수 있기 때문에 필요하다는 주장이다. 한마디로, 빠른 이해를 돕기 위해 필요하다.

반대파

대체로 agile 관련 자료에서 이러한 주장을 많이 보았다. 핵심은 주석이 필요없을 정도로 깔끔하고 이해하기 쉬운 코드를 만들어야 한다는 것이다. 즉, 좋은 품질의 코드(적절한 길이의 함수로 추상화, 적절한 네이밍, 스타일 가이드를 잘 준수하는 등)를 유지해야 한다는 전제가 깔려있다.

이렇게 만들어진 코드라면, 코드만 봐도 이해하는데 무리가 없으니 주석은 중복되는 불필요한 정보를 전달하게 될 뿐이고 독자들에게 혼란만 가중시킨다는 주장이다.

정리

개인적으로는 주석이 꼭 필요한 부분에만 간결하게 작성하고, 주석이 필요없을 정도의 코드 품질을 유지하는게 맞는 방향같다. 이처럼 완전히 찬성이나 반대가 아니라 상황에 따라 적절한 포지션을 선택해야 한다고 생각한다. 주석의 필요성보단 개발자가 얼마나 책임감을 가지고 일하느냐(자신의 코드를 미래의 독자를 얼마나 고려해서 코딩, 문서화하느냐)가 더 중요하다.

고민해보면 찬성파든 반대파든 공통으로 생각하는 가치는 독자가 이해하는데 도움이 되어야 한다는 것이다. “주석을 무조건 작성해야 한다 vs 작성하지 말아야한다“는 흑백논리 같은 단순한 규칙으로 복잡한 문제들을 모두 해결할 수 없지 않을까? 이 논쟁을 가치없다고 매도하는건 아닌다.

대세가 waterfall에서 agile로 변화하면서 코드 주석을 부정적으로 이야기하는 글들이 늘어났다는사실을 구글링하는 도중에 깨달았다. Agile을 채택해서 코드 품질을 지속적으로 개선하면 주석을 사용할 필요가 전혀 없는다는 이야기는 단순한 이상론으로 들린다. 필요한 부분에 최소한으로 작성하는 주석은 정말 유용하다. 내가 유용하다고 느꼈던 부분들은 아래와 같다.

1. TODO, FIXME, NOTE … 주석들은 요즘 인기있는 IDE(Visual studio, Eclipse, IntelliJ, …)들이 지원하는 키워드들이다. 에디터 화면에서 강조해주고, 별도 리스트로도 표시하기 때문에 모르고 지나치기도 어렵다. 특히 TODO는 자주 애용하는데, 생산성 차이가 많이 난다.

   이러한 주석이 너무 많이 쌓이면 관리, 유지보수하기 힘들다는 의견도 있고 어느 정도 동의한다. 하지만 주석 자체의 문제라기보단 개발 일정이나 개발자 의지 같은 외부적인 요인이 더 큰 원인이 아닌가 싶다.

2. Doxygen, javadoc 등의 문서화 도구가 사용하는 주석으로, 작성하기 번거롭기는 해도 그 유용성은 더 설명할 필요가 없다. 다만, 프로젝트 성격에 따라 문서를 보는 독자가 있는지 정도는 고민이 필요하다.

3. 코드의 알고리즘이나 스펙 등이 어려워 설명이 필요한 경우, 리팩토링만으로는 한계가 있는 경우가 있다. 내 실력 부족일 수도 있지만, 이 경우에 한해서는 리팩토링에 시간을 들이기보다 간결한 알고리즘 설명을 주석으로 남기는 편이 더 쉽다.

   커밋 메세지에 설명을 적어 이력으로 남기는 방법도 있다. 하지만 코드 상에서 바로 보는 것보단 느리며 소프트웨어 프로젝트는 팀플레이라는 사실을 잊으면 안된다. 좋은 도구를 사용해서 커밋 이력을 빠르게 참조하면서 분석하는 사람이 있는가 하면, 아닌 사람들도 존재한다. 상황이 항상 이상적이라고 섣불리 판단하는 태도는 교만하고 위험하다. 나와 예비 독자인 개발자들이 어떤 도구를 선호하고 코드를 분석하는 능력이 어느 정도인지도 충분히 파악하고 고려해야 한다.

자신이 처한 환경에서 충분히 고민하고 적절한 전략을 취하는 것. 무책임하게 들릴 수 있지만 그게 내가 생각하는 좋은 방법이다.