[클린코드 스터디] 4장. 주석

4장. 주석

🧾 주석은 ‘필요악’이다

주석은 좋은 코드의 대체재가 아니다.
주석이 많다는 건, 어쩌면 코드만으로는 의도가 잘 전달되지 않았다는 신호일 수도 있다.

물론 주석이 항상 나쁘다는 뜻은 아니다.  필요한 경우도 분명히 있다.

다만 이 장에서는 이렇게 강조한다:

“주석은 실패의 징후다.”

조금 과감한 표현이지만, 그만큼 ‘주석 없이도 충분히 읽히는 코드’를 지향하자는 메시지로 받아들이면 좋을 것 같다.
주석을 달기 전, “혹시 코드 자체로 더 명확하게 표현할 수는 없을까?” 하고 한 번쯤 되돌아보는 습관이 필요하다는 이야기다.

❌ 나쁜 주석 vs ✅ 좋은 주석

❌ 나쁜 주석

• 코드를 보완하려는 변명용 주석
• 너무 오래돼서 사실과 어긋난 주석
• 중복되거나 의미 없는 설명
• 주석으로 처리해버린 죽은 코드
• 너무 장황하거나 모호한 표현

✅ 좋은 주석

• 법적, 라이선스 관련 설명
• 정규식, 날짜 포맷 등 익숙하지 않은 표현 설명
• 구현 방식에 대한 결정 의도 공유
• 경고성 안내, 테스트 조건, // TODO 주석 등

💥 주석이 문제가 되는 이유

• 시간이 지나면 코드만 바뀌고 주석은 방치되기 쉽다
• 잘못된 주석은 없는 것보다 더 위험하다
• IDE, 버전 관리가 있는 지금은 “주석 이력”도 불필요하다

진실은 코드에 있다.
코드만이 자기 일을 진실되게 말한다.

🛠 주석보다 더 좋은 선택: 코드로 말하자

주석을 달기 전에 이렇게 생각해보자.
“이걸 함수로 빼거나, 변수 이름을 바꾸면 설명 없이도 알 수 있지 않을까?”

💬 예시 1: 조건문 설명을 함수로 바꾸기

// 직원이 복지 혜택 대상인지 확인 if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

→ 이렇게 바꾸면 주석이 필요 없다:

if (employee.isEligibleForFullBenefits())

 

💬 예시 2: 계산 주석 대신 변수로 분리

// 기본 급여 + 수당 - 세금 double salary = (basePay + bonus) - tax;

 

→ 더 읽기 쉬운 방식:

double grossIncome = basePay + bonus; double salary = grossIncome - tax;

🧹 그밖에 피해야 할 주석 습관

• 주석으로 처리된 코드 → 지우고 Git에 맡기자
• 닫는 괄호 옆 주석 → 함수가 너무 크다는 신호일 수 있음
• 배너처럼 줄 긋는 주석 → 필요없음1
• 의미 없는 Javadoc (/** the name */) → 필요없음2
• 전역 시스템 설명을 특정 함수 주석에 → 혼란만 줌

---

✍️ 마무리하며

“주석은 실패를 만회하는 수단이지, 자랑할 게 아니다.” 

조금 강하게 들릴 수도 있지만, 이 말의 핵심은 “코드 자체가 말할 수 있다면 굳이 주석에 의존하지 않아도 된다”는 뜻이다.

정말 필요한 경우가 아니라면, 주석을 달기 전에 코드로 더 잘 표현할 방법이 없는지 먼저 고민해보자.
의도를 드러내는 이름, 짧고 명확한 함수, 간결한 구조만으로도 읽기 좋은 코드는 충분히 가능하다.

 

조금씩 개선해나가며 주석 없이도 의도가 보이는 코드를 만드는 습관을 가져봐야겠다👊