04장 주석(Comments)

📘 클린 코드 북스터디 정리입니다

📚 도서: 로버트 C. 마틴 《Clean Code》
🧑‍💻 목적: 좋은 코드에 대한 감각과 습관을 익히기 위해
🗓️ 진행 기간: 2025년 5월 ~ 매주 2장

---

📖 [04장] 주석

✅ 핵심 요약 (Key Takeaways)

이 장의 핵심 문장

나쁜 코드에 주석을 달지 마라. 새로 짜라.
— 브라이언 W. 커니핸, P.J. 플라우거

저자가 전달하고자 하는 메시지 요약

• 주석은 보통 실패한 코드를 보완하려는 시도이며, 대부분의 주석은 필요하지 않다.
• 주석이 필요하다고 느껴진다면, 의도를 코드로 직접 표현하는 방식을 먼저 고민해야 한다.
• 다만, 법적 주석, 공개 API용 Javadoc, 결과를 경고하거나 의도를 명확히 설명하는 소수의 예외적 주석은 유용할 수 있다.
• TODO 주석은 일정 관리 도구처럼 사용하되, 주기적으로 검토하여 제거하는 것이 바람직하다.
• 중복되거나 모호하거나 코드로 대체 가능한 주석은 오히려 오해를 낳고 코드를 복잡하게 만든다.

---

💡 내용 정리

✅ 필요하거나 유용한 주석

• 법적인 주석: 저작권 및 소유권 등 회사가 요구하는 법적 정보. 예) 소스 파일 첫 머리의 저작권 정보와 소유권 정보
• 기본 정보를 제공하는 주석: 예) 추상 메서드의 반환값 설명
• 의도를 설명하는 주석: 코드만으로 드러나지 않는 설계나 사용 의도를 설명
• 의미를 명료하게 밝히는 주석: 모호한 인수/반환값의 의미를 명확히 표현해서 독자가 이해하기 쉽도록 하는 주석
• 결과를 경고하는 주석: 특정 동작의 부작용이나 예외 상황 등을 미리 경고하는 주석
• TODO 주석: 당장 구현이 어려운 업무를 표시 (→ 주기적 정리 권장)
• 중요성을 강조하는 주석: 자칫 간과하기 쉬운 코드의 중요성을 강조하는 주석
• 공개 API용 Javadoc: 독자를 위한 명세 문서 역할로 잘 작성될 경우 매우 유용한 주석

❌ 나쁜 주석

• 대다수의 주석은 나쁜 주석: 허술한 코드, 미숙한 결정 등을 감추기 위한 주석
• 주절거리는 주석: 의미 없는 설명을 주절거리는 주석
• 중복 주석: 이미 코드로 표현된 내용을 재차 반복하는 주석
• 오해의 소지가 있는 주석: 코드와 불일치하거나 애매한 표현을 포함하는 오해의 소지가 있는 주석
• 함수/변수로 대체 가능한 주석: 주석이 필요하지 않도록 코드를 개선하는 것이 더 나은 주석
• 닫는 괄호 주석 (// end if): 코드 구조 개선으로 해결 가능
• 배너 주석: 꼭 필요한 경우가 아니면 지양
• 주석 처리된 코드: 형상관리 시스템(Git 등)에 맡기고 삭제하는 편이 좋은 주석
• HTML 주석: 읽기 어렵고 불필요한 주석
• 시스템 전반을 설명하는 주석: 유지보수 되지 않는 경우가 다수인 주석. 주석은 코드 근처에 작성할 것.
• 흥미 위주의 역사/관련 없는 정보: 현재 코드 이해에 도움이 되지 않는 주석.
• 코드와 대응이 불명확한 주석: 주석 위치나 범위가 모호한 주석

---

💡 인상 깊었던 문장 & 나의 인사이트

책에서 가장 기억에 남는 문장

주석은 나쁜 코드를 보완하지 못한다.
표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

해당 문장이 인상 깊었던 이유

이 문장들이야말로 이번 장의 핵심 메시지를 가장 명확하고 강렬하게 전달한다고 느꼈다.
아무리 주석을 잘 작성해도, 결국 실행되는 것은 코드다.

주석에 공을 들이기 전에, 코드를 더 잘 쓰는 것에 집중해야 한다.

주석은 코드의 부족함을 보완할 수 없으며, 좋은 코드가 우선이다.

사실 나는 코드를 작성할 때 주석을 많이 작성하는 편은 아니다.
그래서 이따금씩 동료로부터 "주석을 좀 달아달라"는 피드백을 받은 적이 있었다.
당시엔 단순히 설명을 요구하는 말로 받아들였지만,
지금 와서 생각해보면 그것은 코드 자체의 명확성이 부족하다는 신호였던 것 같다.
즉, 주석을 요구한 것이 아니라, 더 읽기 쉬운 코드와 명확한 의도 표현을 원한 것이었다.

"아차!" 싶다.

주석이 필요하다고 느껴진다면, 우선 코드를 되돌아보자.

---

🛠 실무 적용 아이디어 (To Action)

오늘부터 실천할 작은 실천

• 주석을 작성해야 할 필요성을 느꼈다면, 먼저 코드를 리팩토링할 수는 없는지 확인해보기