주석 없는 코드가 좋은 코드일까? 20년 차 개발자가 말하는 클린 코드와 최악의 주석들

 

오늘 아침, 커피를 한 잔 내리고 무려 7년 전에 제가 짜두었던 레거시 시스템을 수정할 일이 있었습니다. 모니터 화면을 가득 채운 초록색 주석들을 보며 저도 모르게 피식 웃음이 나더라고요. 마치 고대 이집트의 상형문자를 해독하는 고고학자가 된 기분이랄까요? "이때는 대체 무슨 생각으로 이런 장문의 일기를 코드에 써놓았을까?" 싶으면서도, 한편으로는 "아, 이때 이래서 이렇게 짤 수밖에 없었지" 하며 과거의 저에게 진심으로 고마움을 느꼈습니다.

오늘은 개발자라면 누구나 한 번쯤 밤새워 토론해 봤을 법한 이야기, **'코드의 주석'**에 대해 편안하게 수다를 떨어볼까 합니다.

 

1. 주석, 도대체 얼마나 달아야 할까요?

개발자들 사이에서 영원히 끝나지 않는 논쟁거리가 있죠. "주석 없는 코드가 가장 좋은 코드다" vs "그래도 주석은 꼼꼼히 적어야 한다"

'클린 코드'의 유토피아와 현실

요즘은 변수명과 함수명 자체로 의도를 명확히 드러내어, 주석이 필요 없는 코드를 지향하는 것이 대세입니다. CoLife 역시 이 방향성에 전적으로 동의합니다. // 유저 나이를 계산한다 같은 주석보다는 calculateUserAge()라는 함수명이 훨씬 아름답고 직관적이죠.

하지만 현업에서 치열하게 구르다 보면, 코드가 소설책처럼 술술 읽히는 유토피아는 잘 오지 않습니다. 복잡한 비즈니스 로직, 기획팀의 갑작스러운 예외 케이스 처리, 특정 브라우저 버그를 우회하기 위한 꼼수(?)들이 들어가기 시작하면 코드만으로는 도저히 맥락을 파악하기 힘들어지는 순간이 반드시 옵니다.

 

2. 거짓말쟁이 주석: 코드는 A인데 주석은 B라고 우기는 참사

개발을 하다 보면 차라리 주석이 없었다면 3시간 만에 끝났을 디버깅을, 잘못된 주석 때문에 꼬박 하루를 날려버리는 경우가 있습니다. 저는 이걸 **'거짓말하는 주석'**이라고 부릅니다.

• 동기화되지 않은 주석의 파괴력: 버그를 고치거나 로직을 수정할 때, 다급한 마음에 코드는 고치면서 위에 달린 주석은 예전 그대로 방치하는 경우가 많습니다.
• 스노우볼이 되는 기술 부채: 후임자나 미래의 동료는 당연히 그 주석을 믿고 로직을 파악합니다. 코드는 이미 다른 방향을 향해 가고 있는데, 주석이 엉뚱한 길을 가리키고 있으니 깊은 함정에 빠지게 되는 거죠.

업데이트 안 할 거면 차라리 다 지워주세요. 코드와 동기화되지 않고 썩어가는 주석은 오래된 레거시 코드보다 훨씬 더 무섭고 파괴적입니다.

 

3. 버리지 못하는 병, 코드 호더(Hoarder)와 좀비 코드

가장 곤란하고 답답한 경우는 수백 줄의 코드가 /* ... */로 칭칭 감겨 주석 처리된 채 방치되어 있는 이른바 **'주석 무덤'**을 발견할 때입니다.

"'혹시 몰라서' 주석 처리해 둔 500줄짜리 코드, 5년째 방치 중이시죠?"

"언젠가 다시 쓸지도 몰라", "기획팀이 다시 살려내라고 할 수도 있어"라는 명목하에 로직 전체를 주석 처리해 두는 분들이 꽤 많습니다.

• "이 코드는 왜 막아둔 거지? 에러가 나서 막은 건가?"
• "내가 이걸 지우면 시스템이 무너지는 건 아닐까?"

이유가 적혀있지 않은 **좀비 코드(주석 처리된 채 죽어있는 코드)**는 후임자들에게 엄청난 공포감을 줍니다. 결국 아무도 건드리지 못하고 소스 파일의 스크롤만 길게 만드는 흉물로 전락하죠.

우리에게는 Git이라는 훌륭한 타임머신이 있습니다. 형상관리 도구를 믿으세요. Git Blame과 커밋 히스토리가 여러분의 과거를 모두 기억하고 있습니다. 쓰레기통이나 백업 폴더를 굳이 소스코드 한가운데에 두지 마세요. 과감하게 지우는 것도 용기입니다.

 

4. CoLife가 생각하는 '좋은 주석'의 조건

결론부터 말씀드리면, 좋은 주석은 '무엇(What)'이 아니라 '왜(Why)'를 설명하는 주석입니다. 기능은 코드가 설명하지만, 그 코드가 그렇게 짜일 수밖에 없었던 '역사적 배경'은 오직 주석만이 알려줄 수 있습니다.

• 나쁜 주석: // 두 값을 더해서 총합을 구한다. (코드를 보면 누구나 아는 사실)
• 좋은 주석: // 2024년 3월 재무팀 요청: A부서와 B부서의 매출 산정 방식이 달라 예외적으로 합산 처리함.

특히 어떤 로직을 잠시 주석 처리(Comment-out)해야 하는 불가피한 상황이라면, 반드시 그 이유를 적어야 합니다. *"오류 나서 임시로 막음"*이 아니라, *"2024년 벚꽃 이벤트 종료로 임시 비활성화 (내년 봄 재사용 예정이므로 삭제 금지)"*라고 적어두면, 1년 뒤의 나와 동료들에게 훌륭한 이정표가 됩니다.

 

💡 20년 차의 실전 생존 노하우: 내 기억력을 절대 믿지 마라

오랜 시간 코드를 짜며 뼈저리게 배운 진리가 하나 있습니다. 내가 짠 코드라도 3개월이 지나면 남이 짠 코드와 다를 바 없습니다. 치명적인 장애가 발생해서 새벽 3시에 비몽사몽 노트북을 열고 코드를 본다고 상상해 보세요. 그때 여러분을 살리는 건 화려한 디자인 패턴이나 최신 아키텍처가 아니라, 투박하지만 명확하게 적혀있는 한 줄의 주석입니다. 미래의 나, 그리고 이 코드를 물려받을 누군가를 위해 친절한 편지를 쓴다는 마음으로 '의도'를 남겨두세요.

업무 정책이 변경되어 로직을 수정할 때도 과거의 주석을 그냥 덮어쓰기보다는, *"2022년에는 A로 계산했으나, 2024년 정책 변경으로 B로 수정함"*처럼 히스토리를 누적해 두는 것이 나중에 장애 원인을 파악할 때 훨씬 유리합니다. 개발은 결국 사람과 사람이 이어가는 마라톤이니까요.

 

마무리하며

우리는 늘 깔끔하고 완벽한 코드를 꿈꾸지만, 현실은 복잡한 요건과 타협하며 수많은 주석을 껴안고 살아갑니다. 하지만 그 지저분해 보이는 주석들 속에 우리가 밤낮으로 고민했던 흔적과 치열했던 삶의 조각들이 녹아있는 게 아닐까요?

물론 거짓말하는 주석과 좀비 코드는 솎아내야겠지만요! 😊

독자 여러분은 어떠신가요? 이해할 수 없는 기괴한 주석을 발견하고 빵 터졌던 경험이나, 과거의 내가 남긴 주석 덕분에 위기를 모면했던 적이 있으신가요? 여러분의 재미있는 에피소드를 댓글로 편하게 들려주세요!