클린 코드, 50년 인생의 지혜를 담아 주석 없이 설명하는 코드 작성법
"이 코드는... 제가 짠 게 맞나요?"
불과 몇 달 전, 야근까지 해가며 완성했던 코드가
마치 고대 상형문자처럼 느껴지는 순간, 다들 경험해보셨을 겁니다.
분명 미래의 나를 위해 친절한 주석까지 남겨뒀지만,
어느새 코드와 주석은 서로 다른 이야기를 하고 있죠.
결국 우리는 커피를 한 잔 더 타 와서,
자신이 만든 미궁을 처음부터 다시 탐험해야 하는 운명에 처합니다.
50년 넘게 살아보니 깨닫게 되는 지혜가 있습니다.
진정한 신뢰는 화려한 미사여구가 아닌, 일관된 행동에서 비롯된다는 것을요.
코드의 세계도 마찬가지입니다. 훌륭한 코드는 주석이라는 변명 뒤에 숨지 않습니다.
코드 그 자체가 자신의 존재 이유와 철학을 명확하게 증명해냅니다.
오늘, 우리는 주석이라는 목발을 버리고 두 발로 당당히 서는 코드를 만드는,
단순한 기술이 아닌 '장인의 태도'에 대해 이야기해보고자 합니다.
🚀 1원칙: 이름, 그 안에 우주를 담아라
우리가 건축가라고 상상해봅시다.
설계도에 '기둥1', '벽A' 라고만 적어둔다면,
그 건물이 어떤 철학을 담고 있는지 누구도 알 수 없을 겁니다.
코드에서 변수와 함수의 이름은 설계도의 기둥과 벽 이름과 같습니다.
`data`, `temp`, `value` 같은 이름은 '그냥 무언가'라고 말할 뿐,
그것이 건물의 하중을 견디는 '내력 기둥'인지,
햇빛을 조절하는 '장식 벽'인지 전혀 알려주지 않죠.
변수/상수: '이것은 무엇인가?'에 대한 완벽한 대답 (명사).
(예: `list` → `approvedUserAccounts`)
함수: '이것은 무엇을 하는가?'에 대한 명쾌한 행동 (동사).
(예: `handleData()` → `validateAndSaveUserInput()`)
이름은 길어져도 괜찮습니다. 모호한 것보다 장황한 것이 천 배는 낫습니다.
코드를 직접 보며 그 차이를 느껴보시죠.
// Before: 주석이 없으면 의도를 추측해야 한다.
// 480분(8시간) 이상이면 true
function check(t) {
return t > 480;
}
// After: 코드가 스스로 의도를 노래한다.
const MINUTES_IN_FULL_WORK_DAY = 480;
function hasCompletedFullWorkDay(elapsedMinutes) {
return elapsedMinutes > MINUTES_IN_FULL_WORK_DAY;
}
좋은 이름은 코드를 읽는 동료의 시간을 아껴주는 최고의 배려입니다.
💡 2원칙: 오직 한 가지 일에 통달하라
평생 하나의 우물만 판 장인이 최고의 물맛을 아는 법입니다.
코드의 세계도 다르지 않습니다.
하나의 함수가 데이터베이스에서 정보를 가져와서(DB 담당),
그 정보를 비즈니스 규칙에 맞게 가공하고(기획 담당),
마지막으로 예쁜 HTML 형태로 만들어 사용자에게 보여준다면(디자인 담당),
그 함수는 너무 많은 역할을 떠안은 '만능 신입사원'과 같습니다.
결국 과로로 쓰러지거나, 예상치 못한 버그를 만들어내기 마련이죠.
함수는 작아야 하고, 오직 한 가지 책임에만 통달해야 합니다.
이것이 바로 단일 책임 원칙(SRP)이라는 위대한 지혜입니다.
✅ 함수의 역할을 한 문장으로 설명할 때 '...하고, 그리고...'라는 말이 들어가는가?
✅ 함수를 테스트하기 위해 너무 많은 사전 설정이 필요한가?
✅ 함수 내에 논리적으로 구분되는 빈 줄이 여러 개 있는가? (서로 다른 일을 하고 있다는 신호!)
거대한 '만능 함수'를 여러 개의 '전문가 함수'로 나누는 순간,
코드는 마치 잘 조직된 전문가 팀처럼 일사불란하게 움직이기 시작합니다.
🔧 3원칙: 코드를 한 편의 이야기로 써라
우리는 소설을 읽을 때 위에서 아래로, 자연스럽게 흐름을 따라갑니다.
좋은 코드 역시 독자가 그렇게 읽을 수 있어야 합니다.
갑자기 세부적인 구현 내용이 튀어나와 이야기의 흐름을 끊어서는 안 됩니다.
가장 높은 수준의 정책(가장 큰 그림)이 맨 위에 나오고,
그 정책을 구현하는 세부적인 내용들은 더 아래쪽 함수에 위임되어야 합니다.
마치 신문 기사처럼, 가장 중요한 헤드라인이 먼저 나오고
점점 더 구체적인 내용으로 파고드는 것과 같죠.
이를 위해 복잡한 조건문이나 계산식을 함수로 추출하는 기법은
이야기의 흐름을 매끄럽게 만드는 최고의 도구입니다.
// Before: '무엇'을 하는지보다 '어떻게' 하는지에 집중하게 된다.
if ((user.level === 'GOLD' || user.purchaseAmount > 1000) && user.isLoggedIn && !user.isBlacklisted) {
// 할인 적용 로직...
}
// After: 코드가 마치 비즈니스 요구사항처럼 읽힌다.
if (isCustomerEligibleForVipDiscount(user)) {
applyVipDiscount(user);
}
이렇게 작성된 코드는 주석이 필요 없을 뿐만 아니라,
기획자나 다른 팀원과 소통하는 강력한 도구가 됩니다.
• 주석 처리된 코드: 왜 남겨뒀는지 아무도 모르는 코드의 유령. 버전 관리는 Git에게 맡기고 과감히 삭제하세요.
• 의도가 불분명한 매개변수: `calculate(true, false, 10)` 과 같은 코드는 최악입니다. `calculate({ useCache: true, applyDiscount: false, maxRetries: 10 })` 처럼 객체를 사용해 의도를 명확히 하세요.
• 깊은 들여쓰기: 3단계 이상의 `if-for-if` 중첩은 함수가 너무 많은 일을 하고 있다는 강력한 증거입니다. 즉시 분리하세요.
✨ 결론: 침묵으로 증명하는 장인의 코드
주석은 왜 나쁠까요?
주석은 코드가 자신의 의도를 제대로 표현하지 못했다는 '패배 선언'과도 같기 때문입니다.
더 무서운 것은, 주석은 코드와 함께 진화하지 않는다는 점입니다.
코드는 계속 바뀌지만 주석은 잊혀지고, 결국 거짓말을 하는 주석이 되어
미래의 개발자에게 더 큰 혼란을 줍니다.
• 시간의 절약: 코드를 읽고 이해하는 시간이 줄어들어, 진짜 문제 해결에 더 집중할 수 있습니다.
• 품질의 향상: 코드가 명확해지면 숨어있던 논리적 오류가 자연스럽게 드러납니다.
• 성장의 즐거움: 자신의 코드가 하나의 잘 만들어진 예술품처럼 느껴질 때, 개발자로서의 자부심과 성장의 기쁨을 맛보게 됩니다.
진정한 장인은 자신의 작품에 대해 구구절절 설명하지 않습니다.
작품 자체가 모든 것을 말해주기 때문이죠.
우리의 코드도 마찬가지입니다. 주석이라는 시끄러운 변명 대신,
잘 짜인 구조와 명료한 이름이 빚어내는 '우아한 침묵'으로
우리의 실력과 철학을 증명해야 하지 않을까요?
#클린코드, #CleanCode, #리팩토링, #소프트웨어장인정신, #개발문화, #코드리뷰, #개발자성장, #개발꿀팁, #프로그래밍철학, #코딩습관, #주석없이코딩하기, #가독성, #유지보수, #IT정보, #개발노하우