개발자라면 귀에 딱지가 앉도록 들었을 말이 하나 있습니다.
"주석은 '무엇(What)'이 아니라 '왜(Why)'를 설명해야 한다."
클린 코드(Clean Code)의 철학을 따르는 우리는 이 말을 금과옥조처럼 여깁니다.
코드가 '무엇'을 하는지는 코드로 말해야지, 주석으로 설명하려 든다면 그건 실패한 코드라는 거죠.
저도 주니어 시절엔 그랬습니다.
후배가 로직 설명하는 주석을 달아오면 "변수명을 더 명확하게 짓고 주석은 지우세요"라고 리뷰를 남기곤 했어요.
그런데 10년 넘게 코드를 짜고 운영하다 보니,
이 원칙이 때로는 우리를 더 피곤하게 만든다는 걸 깨달았습니다.
오늘은 조금 도발적인 이야기를 해보려 합니다.
때로는 주석이 '무엇'을 설명하는 게 훨씬 낫습니다.
물론, 나쁜 코드의 변명으로 주석을 쓰라는 말이 아닙니다.
예를 들어 이런 코드는 여전히 최악입니다.
w = 10; // 너비 설정
이건 그냥 변수명을 width로 바꾸면 해결될 일이죠.
이런 건 논쟁의 여지가 없습니다.
제가 말하고 싶은 건 복잡한 로직의 흐름입니다.
우리는 흔히 함수가 길어지면 "쪼개라"고 배웁니다.
엉클 밥(Bob Martin)의 "더 이상 쪼갤 수 없을 때까지 쪼개라(Extract Till You Drop)" 원칙이죠.
어떤 복잡한 문자열 치환 로직이 있다고 칩시다.
원래는 10줄짜리 코드 하나였습니다.
그런데 클린 코드를 실천하겠다고 이걸 6개의 작은 메서드로 쪼갭니다.
replace()replaceAllSymbols()nextSymbol()replaceAllInstances()
...
자, 이제 코드를 읽어봅시다.
메인 함수를 봅니다. replaceAllSymbols()가 호출되네요.
"이게 뭐 하는 거지?"
정의된 곳으로 점프합니다. (스크롤 이동)
거기엔 nextSymbol()이 있네요. 또 점프합니다. (스크롤 이동)
그 안엔 symbolMatcher.find()가 있습니다.
다시 위로 올라가서 다른 메서드를 봅니다.
어지럽지 않나요?
코드는 짧아졌을지 몰라도, 전체 흐름을 파악하기 위해 시선이 위아래로 널뛰기를 합니다.
이걸 전문 용어로 문맥 전환(Context Switching) 비용이라고 합니다.
함수 이름을 기가 막히게 지으면 된다고요?
하지만 디버깅을 할 때는 이름만 보고 넘어갈 수 없습니다.
결국 내부 구현을 확인해야 하고, 그때마다 파일 이곳저곳을 헤매야 합니다.
오히려 정보가 파편화되는 거죠.
이럴 때, 차라리 적당히 뭉쳐진 코드 위에 '무엇'을 하는지 설명하는 주석 한 줄이 있다면 어떨까요?
코드 덩어리는 한곳에 모여 있습니다. (Locality)
주석을 읽으니 대략 무슨 일을 하는지 알겠습니다.
세부 구현이 궁금하면 바로 아래 10줄을 읽으면 됩니다.
다른 함수로 점프할 필요가 없죠.
시선의 흐름이 끊기지 않습니다.
이게 훨씬 '읽기 쉬운 코드' 아닐까요?
물론 '왜'를 설명하는 주석은 여전히 중요합니다.
가끔 말도 안 되는 코드가 보일 때가 있죠.
library.clear();library.clear();
"아니, 왜 두 번이나 호출해? 실수인가?"
이때 누군가는 "커밋 메시지(git blame)를 확인하라"고 합니다.
하지만 현실적으로 코드를 읽다가 터미널을 열고, git blame을 치고, 커밋 로그를 뒤지는 건 엄청난 문맥 전환입니다.
귀찮아서 그냥 "실수겠지" 하고 한 줄을 지워버릴 수도 있습니다.
그러다 장애가 나겠죠.
이때는 코드 옆에 바로 적어줘야 합니다.
// 라이브러리 버그(ABC-123)로 인해 두 번 호출해야 완전히 초기화됨
이 정보는 커밋 로그가 아니라, 코드가 실행되는 그 현장에 있어야 합니다.
결국 핵심은 '인지 부하(Cognitive Load)'를 줄이는 것입니다.
무조건 함수를 잘게 쪼개는 게 능사가 아닙니다.
무조건 주석을 없애는 게 정답도 아닙니다.
코드를 읽는 동료(혹은 미래의 나)가 스크롤을 덜 하고, 덜 찾아보고, 덜 고민하게 만드는 방법을 선택하세요.
그게 함수를 합치고 '무엇'을 하는지 주석을 다는 것이라면, 과감하게 그렇게 하세요.
우리는 '클린 코드 교과서'를 만드는 게 아니라,
살아서 돌아가는, 유지보수 가능한 제품을 만드는 엔지니어니까요.
오늘 작성한 코드에 주석을 달까 말까 고민되시나요?
그 주석이 동료의 스크롤 질을 한 번이라도 줄여줄 수 있다면,
망설이지 말고 적으세요.
'무엇'을 설명하더라도 괜찮습니다.
