많은 개발자가 코드에 주석을 남기는 걸 좋아하지 않습니다. 개발자 사이에서 “주석이 아닌 코드로 설명할 수 있어야 제대로 된 코드다”라는 믿음은 살짝 과할 정도로 강합니다. 어쩌면 이 글의 제목에서부터 불편하신 분도 있을 것 같습니다.
저는 주석을 남기는 것을 옹호합니다. 개발은 혼자 하는 것이 아닙니다. 개인 프로젝트를 할 때도 마찬가지입니다. 지금의 나와 미래의 나는 사실상 다른 사람이라 보는 것이 옳습니다. 타인의 이해를 위해 주석을 남기는 것은 친절의 영역이며 결코 과하지 않습니다.
제가 주석이 유용하다고 여기는 세 가지 관점은 다음과 같습니다.
📍 주석은 가이드입니다.
처음 코드를 보는 사람은 어떤 코드인지 알기 힘들 수 있습니다. 코드 자체로 설명이 된다면 가장 좋겠지만 아무리 선언적으로 짜도 한계가 있을 수 있습니다. 이럴 때 주석은 어디서부터 어떻게 코드를 봐야 할지 알려주는 가이드 역할이 될 수 있습니다.
📍 주석은 히스토리를 설명합니다.
모든 코드엔 나름의 역사가 있습니다. 코드는 완벽한 상태를 유지하는 것이 거의 불가능합니다. 오히려 일정의 압박, 비즈니스적인 이유로 인해 납득할 수 없는(제삼자가 보기에) 코드가 될 수도 있습니다. 그렇지만 주석을 통해 이 지경이 된 이유를 남겨놓는다면 코드에 대한 불쾌감이 아닌 이해의 영역으로 넘길 수 있습니다. 이해할 수 있게 된다면 앞으로 어떻게 개선할지에 대해 논의할 수 있게 됩니다.
📍 주석은 레퍼런스입니다.
아무리 똑똑하더라도 처음 보는 코드가 복잡하다면 이해하기 어렵습니다. 코드 베이스가 크다면 어디부터 파악해야 할지 감을 잡는 것도 쉽지 않습니다. 이런 경우를 대비해 주석을 통해 어떤 문서를 봐야 할지 알려줄 수 있습니다. 코드에 담을 수 없는 UML 등의 도식, 비즈니스 설명, 연관 모듈 등에 대한 문서를 링크로 남겨 코드 베이스에 대한 학습을 유도할 수 있습니다. 이를 통해 코드오너쉽을 향상할 수도 있습니다. 혹은 적절한 온보딩의 도구로 사용할 수도 있습니다.
타인을 위해 베푸는 친절로서 잠깐의 귀찮음을 무릅쓰고 남기는 주석은 생산성으로 이어질 수도 있습니다. 만약 팀 내 개발 문화로 자리 잡는다면 적절한 수준으로 주석 을 다는 훈련이 될 수도 있습니다.
친절은 부족한 것보다 과한 게 낫습니다. 가독성에 방해되는 주석이 있다면 지우면 그만입니다. 간단한 주석을 통해 오해를 줄이고 친절을 느낀다면 감정 상하는 일 없이 개선에 대한 논의해 볼 수 있게 됩니다.
사실 꼭 주석이 아니어도 됩니다. 원활하게 정보를 공유할 수 있고 활발한 소통을 할 수 있다면 주석을 달지 않아도 됩니다. 하지만 그렇지 않다면 주석을 다는 것부터 시작해 보면 어떨까요?
