시스매

클린 코드 원칙, 양날의 검이 되는 순간들

17 min read

2025-09-20 14:58

  • 클린 코드 원칙은 코드의 가독성과 유지보수성을 높이는 데 필수적인 개념이다.

  • 하지만 원칙을 맹목적으로 따를 때 오히려 코드가 복잡해지고 기술 부채로 이어질 수 있다.

  • 중요한 것은 원칙 그 자체가 아니라, 후임 개발자가 코드를 더 쉽게 이해하고 작업할 수 있도록 만드는 실용적인 균형감이다.

클린 코드 원칙, 양날의 검이 되는 순간들

모든 개발자들이 끊임없이 고민하는 주제 중 하나는 바로 깨끗하고 깔끔한 코드를 작성하는 일이다. ‘클린 코드’라고 불리는 이 개념은 코드베이스가 커질수록 관리를 용이하게 하고, 팀원 간의 협업 효율을 높이는 데 그 목적이 있다. 그러나 클린 코드 원칙을 마치 교과서처럼 맹목적으로 적용할 때, 오히려 역효과를 초래하는 경우가 종종 발생한다. 코드를 아름답게 다듬는 데만 집중하다가 정작 중요한 비즈니스 로직이 감춰지거나, 동료들이 코드를 이해하기 위해 더 많은 시간을 쓰는 딜레마에 빠지는 것이다.

이 핸드북은 클린 코드의 기본 원칙을 짚어보고, 이 원칙들이 현실의 개발 환경에서 어떻게 ‘독’이 될 수 있는지 그 한계와 문제점을 심층적으로 탐구한다. 궁극적으로는 좋은 코드를 만드는 실질적인 목표, 즉 가독성, 단순성, 그리고 유지보수성을 어떻게 하면 가장 효율적으로 달성할 수 있는지에 대한 실용적인 가이드라인을 제시한다.

1. 작은 함수의 함정: 이해를 방해하는 과도한 분할

원칙: ‘함수는 한 가지 일만 해야 하며, 작아야 한다.’ 이는 클린 코드의 가장 기본적이고 널리 알려진 원칙이다. 하나의 함수가 너무 많은 역할을 수행하면 복잡성이 높아지고, 버그 발생 확률이 증가하며, 재사용성이 떨어진다는 논리다.

과도한 적용의 문제점: 이 원칙을 너무 철저히 따르면, 단순한 작업을 위해 여러 개의 작은 함수를 생성하고, 이 함수들이 여기저기 흩어져 코드의 흐름을 따라가기 어렵게 만든다. 예를 들어, 사용자 입력 값을 검증하는 validateInputFields 함수가 있다고 가정해보자. 이 함수는 사용자 이름, 비밀번호, 이메일 등을 검증하는 역할을 한다. 클린 코드 원칙에 집착하면, 이 함수를 validateUsername, validatePassword, validateEmail 등으로 나누고, 심지어 validateUsernameLength와 같이 더 작은 단위로 쪼갤 수도 있다.

현실적인 역효과: 이처럼 코드를 잘게 쪼개는 행위는 겉보기에는 깔끔해 보일 수 있다. 하지만 동료 개발자가 이 코드를 이해하려면 어떻게 될까? 간단한 로그인 프로세스의 흐름을 파악하기 위해 login 함수를 시작으로 validateInputFields를 거쳐, 다시 validateUsername, validatePassword 등 여러 함수와 파일을 오가야 하는 상황이 발생한다. 이는 개발자의 **인지적 부하(Cognitive Load)**를 극도로 증가시킨다. 코드를 이해하는 데 필요한 정보가 여러 위치에 분산되어 있어, 개발자는 전체적인 맥락을 머릿속에 재구성해야 하는 부담을 안게 된다. 결국 코드를 더 쉽게 읽히게 하려던 의도와 달리, 오히려 이해를 방해하는 결과를 초래하는 것이다.

2. DRY 원칙과 복잡한 괴물의 탄생

원칙: ‘Don’t Repeat Yourself’ (DRY), 즉 ‘반복하지 말라’는 원칙은 코드의 중복을 제거하여 유지보수성을 높이는 데 초점을 맞춘다. 동일한 로직이 여러 곳에 존재할 경우, 한 곳을 수정하면 모든 곳을 찾아 수정해야 하는 비효율을 막기 위함이다.

과도한 적용의 문제점: DRY 원칙을 지나치게 의식하면, 비슷하지만 서로 다른 역할을 가진 코드들을 억지로 하나의 함수로 합치려다 오히려 더 복잡한 코드를 만들어낸다. 예를 들어, 회원가입 (signUp)과 로그인 (login) 로직이 있다고 가정해보자. 두 함수는 사용자 입력 처리, 데이터베이스 접근 등 일부 공통된 코드를 포함하지만, 본질적으로는 서로 다른 목적을 가진다. DRY 원칙에 집착하면, 이들을 handleForm이라는 하나의 함수로 묶고, formType과 같은 인자를 받아 내부에서 if-else 또는 switch 문으로 분기 처리하게 된다.

현실적인 역효과: 초기에는 깔끔해 보였던 이 함수는 시간이 지나며 요구사항이 추가될 때마다 새로운 조건문이 덕지덕지 붙어 **‘복잡한 괴물’**로 변모한다. 회원 탈퇴, 비밀번호 찾기 등 새로운 기능이 추가될 때마다 handleForm 함수에 새로운 if 블록을 추가해야 하는 상황에 놓인다. 이처럼 지나친 추상화는 본래 연결되지 않아야 할 로직들을 억지로 묶어, 의존성을 높이고, 유지보수를 어렵게 만든다. 회원가입 로직의 작은 버그를 수정하려다 로그인 로직에 의도치 않은 영향을 미치는 위험이 커지는 것이다.

대안: 이러한 문제를 방지하기 위한 실용적인 대안으로 **‘세 번의 법칙(Rule of Three)‘**이 있다. 이 원칙은 ‘같은 코드가 세 번 이상 반복되기 전까지는 굳이 합치지 말라’는 경험적인 조언이다. 한두 번의 중복은 용인하고, 세 번째 중복이 나타났을 때 비로소 추상화를 고려하는 것이 불필요한 복잡성과 기술 부채를 사전에 방지하는 현명한 방법이다.

3. 자체 설명형 코드의 역설: 주석의 중요성

원칙: ‘좋은 코드는 자체적으로 설명되어야 한다. 주석은 코드가 자신의 의도를 제대로 표현하지 못했다는 증거다.’ 이 원칙은 깔끔한 코드를 옹호하는 이들 사이에서 자주 인용된다. 코드가 명확하면 주석이 불필요하다는 논리다.

과도한 적용의 문제점: 이 원칙을 지나치게 적용하면, 코드를 지나치게 난해하게 만들어 오히려 이해도를 떨어뜨린다. 예를 들어, 특정 조건 하에 사용자를 비활성화하는 if 문이 있다고 해보자.

// A simple and clear example with a comment explaining the "why"
if (user.lastLogin < new Date().setDate(new Date().getDate() - 31)) {
  // 사용자가 31일 이상 로그인하지 않았으므로 비활성화 처리
  user.status = 'inactive';
}

이 코드를 자체 설명형으로 바꾸기 위해 if문의 복잡한 로직을 user.isInactive()라는 함수로 숨겨버리는 경우가 있다.

// A "self-documenting" example that hides the logic
if (user.isInactive()) {
  user.status = 'inactive';
}

겉으로 보기에는 두 번째 코드가 더 깔끔해 보인다. 하지만 isInactive가 정확히 어떤 로직을 포함하고 있는지 알기 위해서는 해당 함수를 찾아 들어가야 한다. 동료 개발자는 isInactive가 ‘31일’이라는 비즈니스 규칙을 의미하는지, 아니면 다른 복잡한 규칙이 있는지 확인하기 위해 코드 베이스를 뒤져야 하는 수고를 감수해야 한다.

현실적인 역효과: 이 과정은 단순한 주석 하나를 읽는 것보다 훨씬 많은 시간과 노력을 필요로 한다. 코드는 **‘무엇(What)‘**을 하는지 뿐만 아니라 ‘왜(Why)’ 그렇게 해야 하는지에 대한 정보를 담아야 한다. 주석은 코드가 다 담아낼 수 없는 ‘왜’에 대한 설명을 제공함으로써 코드의 의도를 명확히 하고, 동료 개발자의 이해를 돕는 중요한 역할을 수행한다. 이처럼 코딩 자체를 문서화하려는 시도가 때로는 코드의 본질적인 동작을 은폐하고, 결국 기술 부채로 발전하는 것이다.

4. 미래를 위한 과도한 설계와 기술 부채

원칙: ‘미래의 변화에 유연하게 대처할 수 있는 코드를 만들어야 한다.’ 이 원칙은 개발자들이 종종 미래에 대한 과도한 예측과 함께 불필요하게 복잡한 추상화를 시도하게 만든다.

과도한 적용의 문제점: 단순히 getUserProfile이라는 간단한 API 호출 함수를 작성해야 할 때, 어떤 개발자는 미래에 생길 수 있는 모든 상황(인증 방식의 변화, 다양한 요청 헤더, 여러 API 엔드포인트)을 고려하여 복잡한 APIClient 클래스를 설계한다. 이 클래스는 다양한 설정 옵션과 유연한 패치 메서드를 포함하며, 마치 모든 종류의 API를 처리할 수 있는 완벽한 도구처럼 보인다.

현실적인 역효과: 이러한 ‘미래 지향적’인 설계는 사실상 현재의 요구사항을 훨씬 뛰어넘는 복잡성을 유발한다. 실제로는 단순한 API 호출 하나만 필요한 상황인데, 복잡한 클래스의 인스턴스를 생성하고, 여러 메서드를 호출하며, 불필요한 설정값을 넘겨야 하는 상황에 처하게 된다. 이처럼 과도한 추상화는 겉으로는 유연해 보이지만, 실제로는 처음 설계자의 상상에만 맞춰 작동하기 때문에 새로운 요구사항이 발생했을 때 오히려 장애물로 작용한다.

대안: 이러한 문제를 피하기 위해 ‘YAGNI(You Ain’t Gonna Need It)’ 원칙을 기억해야 한다. ‘너는 그것이 필요하지 않을 것이다’라는 뜻으로, 현재 요구사항에만 집중하고, 아직 오지 않은 미래에 대한 과도한 준비를 하지 말라는 뜻이다. 단순한 함수로 시작하고, 복잡성이 실제로 증가할 때만 점진적으로 리팩토링하여 추상화하는 것이 훨씬 현명하고 효율적인 접근법이다.

5. 결론: 원칙의 적절한 적용과 목표

클린 코드 원칙은 틀린 것이 아니다. 그것들은 오랜 시간 동안 많은 개발자들의 경험을 통해 검증된 매우 유용한 조언들이다. 그러나 중요한 것은 원칙을 맹목적으로 따르는 것이 아니라, 그 원칙이 추구하는 근본적인 목표를 이해하고 상황에 맞게 현명하게 적용하는 것이다.

궁극적인 목표는 항상 가독성, 단순성, 그리고 유지보수 용이성이다. 코드가 아무리 작은 함수로 쪼개지고, DRY 원칙을 철저히 지켰다고 해도, 동료가 그 코드를 이해하는 데 어려움을 느낀다면 그 코드는 ‘깨끗하다’고 할 수 없다.

실용적인 개발 환경에서 좋은 코드란, 원칙에 대한 집착 없이도 다음과 같은 질문에 답할 수 있는 코드이다.

  • 이 코드를 처음 보는 사람이 5분 안에 그 흐름을 이해할 수 있는가?

  • 새로운 기능을 추가하거나 버그를 수정할 때, 다른 곳에 예상치 못한 영향을 미치지는 않는가?

  • 필요한 경우, 쉽게 확장하거나 수정할 수 있는 구조인가?

클린 코드는 완벽함을 향한 여정이 아니라, 팀원들과의 소통을 위한 공통의 언어를 만드는 과정이다. 원칙에 얽매이기보다, 팀의 상황과 프로젝트의 요구사항에 맞게 가장 효과적인 방법을 찾는 것이 진정한 클린 코드의 실천이다. 오늘 작성한 코드가 내일의 동료에게 ‘최고의 협업 도구’가 되도록 하자.

그래프 뷰

백링크