주석을 언제 작성해야 할까?

여러분은 언제 주석을 작성하시나요? 🤔

 

이전에 회사에서 후임 개발자분께서 이런 질문을 한 적이 있습니다. "코드에 함수마다 주석이 달려 있는데, 어떤 함수에는 설명이 있고, 어떤 함수에는 없어요. 언제 주석을 작성해야 하는 거죠?"라는 질문이었죠.

// 회사 컨벤션

/**
*
*/
function abc () {...}

/**
* 이건 글쓰는 함수 입니다.
*/
function abc () {...}

당시에는 회사 코드 컨벤션에 따라 주석을 작성해 왔고, '여기에는 주석이 있으면 좋겠다'라는 주관적인 기준에 의존하고 있었기 때문에, 명확히 대답하기 어려웠습니다. 결국 "조건이 3개 이상일 때 작성하는 것 같다"는 애매한 답변을 했던 기억이 납니다. 😂

이 질문 덕분에 주석을 언제 작성해야 하는지 더 깊이 고민해 볼 기회가 생겼습니다. 그래서 오늘은 코드에 주석이 필요한 경우를 정리해 보려고 합니다.

코드에서 주석이 필요한 경우

1. 가독성을 위한 코드 영역 구분
   저희 회사에서는 주석을 코드 영역을 구분하는 용도로 자주 사용합니다. 코드가 쭉 나열되어 있으면 가독성이 떨어지기 때문에, 코드 블록 간의 구분을 위해 주석을 넣곤 합니다.

/**
*
*/ 
function handleWrite() {...}

/**
*
*/
function renderForm() {...}

//  
//  
//

return <div>{renderForm()}</div>

이렇게 하면 코드의 구분이 명확해지고, 리턴문 위에 간단한 주석을 남김으로써 리턴 위치(리턴은 항상 가장 아래 작성)를 빠르게 파악할 수 있게 됩니다. 개인적으로 이 방법이 가독성을 높여주고 필요한 부분을 빠르게 찾는 데 좋다고 생각합니다. 하지만 코드가 길어질수록 불필요한 주석이 생기는 단점도 있죠. 이 방식이 과연 좋은지, 다른 곳에서는 어떻게 하는지 항상 궁금합니다. 🤔

2. 특정 비즈니스 로직 설명이 필요할 때
   특정 도메인과 관련된 개념이나 규칙을 구현할 때는 그 의미와 배경을 설명하는 주석이 필요합니다. 예를 들어, 전자 상거래 시스템에서 "VIP 고객에게 특정 할인 혜택을 제공하는 로직"이 있다면, 왜 이 로직이 필요한지, VIP 고객이 어떤 혜택을 받는지 등 문서 링크와 함께 설명하는 주석이 있다면 새로운 팀원이 해당 코드의 목적을 더 빠르게 이해할 수 있을 것입니다.
   
   
3. 중첩된 조건문이 있을 때
   조건문이 중첩되기 시작하면 주석을 작성하는 것이 좋습니다. 물론, 'if문 하나에 주석을 다는 건 너무 과한 거 아닌가?'라고 생각할 수도 있습니다. 하지만 최근에 3년 전에 작성된 코드에서 이슈가 발생했는데, useEffect에 걸린 if문 조건 때문에 꽤 오랜 시간 고민한 적이 있습니다. 단순한 조건이었지만, 이 조건이 왜 추가되었는지에 대한 설명이 전혀 없었고, PM과 저 모두 해당 컨텍스트를 알지 못해 '이걸 정말 지워도 되는 걸까?'라는 고민을 수없이 했습니다. (결국 PM과 논의 끝에 삭제하기로 했습니다.) 단순한 조건이라도 시간이 지나면 다른 기능에 영향을 미칠 수 있습니다. 그때 이유를 설명하는 주석이 있었다면 훨씬 빠르게 해결할 수 있었을 것입니다.
   
   
4. 제약이나 타협적 구현이 있을 때
   현실적인 제약 때문에 이상적인 방법을 사용하지 못할 때도 주석이 필요합니다. 하드 데드라인 때문에 시간이 부족하거나, 라이브러리의 한계로 인해 최적의 방법이 아닌 타협적 구현을 해야 할 때, 그 이유를 명확히 남겨두는 것이 중요합니다. 예를 들어, "이번 스프린트에서는 일부 기능을 스콥 아웃하고 다음 스프린트에서 진행하기로 했다" 같은 설명을 남기면 나중에 코드를 개선하거나 리팩토링할 때 큰 도움이 됩니다. 이렇게 임시로 남긴 TODO 주석이 차후 작업에서 중요한 단서가 되곤 합니다.

 

주석을 최소화 하는게 좋다

어디선가 "주석이 많다는 건 코드의 품질이 좋지 않다는 의미다"라는 말을 본 적이 있습니다. 이유는 간단합니다. 조건이 많다는 건 코드를 잘게 나누지 않았다는 의미이고, 코드가 한 곳에 많이 몰려 있으면 가독성도 떨어지고 디버깅도 어렵기 때문이죠. 그래서 가능하면 주석 없이도 명확하게 작성하는 것이 이상적이겠지만, 현실에서는 항상 그렇게 되지 않기 때문에 적절한 주석이 필요하다고 생각합니다.

이제는 말할 수 있다

주석에 대해 한 번도 깊게 생각해본 적이 없었지만, 이번 기회에 제 생각을 정리해 보니 이제는 명확한 답을 할 수 있을 것 같습니다. 주석은 단순한 기록이 아니라, 팀의 경험과 지식을 축적하는 중요한 방법이고, 주석이 있다면 코드의 의도와 배경을 파악하기 훨씬 쉬워지고, 이는 팀원들 간의 원활한 협업과 유지보수에 크게 기여할 수 있다고 생각합니다.