[태그:] 가독성

“코드는 요구사항을 만족시키는 것만으로는 부족하다. 코드는 반드시 ‘깨끗해야’ 한다.” 전설적인 개발자 로버트 C. 마틴(Uncle Bob)이 그의 저서 ‘클린 코드’에서 던진 이 화두는, 오늘날 모든 프로 개발자가 추구해야 할 핵심 가치가 되었습니다. ‘클린 코드(Clean Code)’란 단순히 버그 없이 동작하는 코드를 넘어, 다른 개발자가 쉽게 읽고, 이해하고, 수정하며, 유지보수할 수 있도록 작성된 코드를 의미합니다. 이는 마치 잘 쓰인 시가 군더더기 없는 표현으로 깊은 의미를 전달하듯, 명료하고 우아하게 자신의 의도를 드러내는 코드입니다.

하지만 ‘깨끗함’이라는 개념은 다소 주관적이고 추상적으로 들릴 수 있습니다. 무엇이 코드를 깨끗하게 만드는 걸까요? 다행히도, 수십 년간 소프트웨어 공학의 대가들이 쌓아 올린 경험 속에는 시대를 초월하여 통용되는 몇 가지 핵심 원칙이 존재합니다. 바로 가독성, 단순성, 의존성 최소화, 중복성 제거, 그리고 추uttab 추상화입니다. 이 5가지 원칙은 서로 얽히고설켜 있으며, 하나를 지키려는 노력은 자연스럽게 다른 원칙들의 충족으로 이어집니다.

본 글에서는 이 5가지 클린 코드의 기둥을 하나씩 깊이 있게 파헤쳐 보고, 나쁜 코드(Bad Code)와 좋은 코드(Clean Code)의 구체적인 비교 예시를 통해 각 원칙을 어떻게 실제 코드에 적용할 수 있는지 그 실천적인 방법을 제시하고자 합니다. 이 원칙들을 체화하고 나면, 여러분의 코드는 더 이상 당신만의 암호가 아닌, 팀 모두를 위한 명쾌한 소통의 도구로 거듭날 것입니다.

---

1. 가독성 (Readability): 코드는 소설처럼 읽혀야 한다

핵심 아이디어: 최고의 코드는 주석이 필요 없는 코드다

클린 코드의 가장 기본적이면서도 중요한 원칙은 바로 가독성입니다. 코드는 컴퓨터가 실행하기 위해 작성되지만, 그 수명 대부분은 사람에 의해 읽히고 수정됩니다. 따라서 코드는 마치 잘 쓰인 한 편의 글처럼, 위에서 아래로 자연스럽게 읽히면서 그 로직과 의도가 명확하게 이해되어야 합니다. 가독성이 높은 코드는 버그를 찾기 쉽고, 새로운 기능을 추가하기 용이하며, 다른 개발자가 프로젝트에 빠르게 적응할 수 있도록 돕습니다.

가독성을 높이는 가장 효과적인 방법은 의미 있는 이름을 짓는 것과 일관된 서식(formatting)을 유지하는 것입니다.

나쁜 코드: 암호 해독이 필요한 이름

Java

// 데이터 처리 로직
public void proc(List<Data> d) {
    int t = 0;
    for (Data i : d) {
        if (i.getStatus() == 1 && i.getVal() > 100) {
            t += i.getVal();
        }
    }
    // ...
}

• proc, d, t, i… 변수와 함수의 이름만으로는 이 코드가 무엇을 하는지 전혀 알 수 없습니다. i.getStatus() == 1 이나 i.getVal() > 100 과 같은 ‘매직 넘버’와 조건문은 코드의 의도를 파악하는 것을 더욱 어렵게 만듭니다.

클린 코드: 이름만으로 의도가 보이는 코드

Java

public void calculateTotalAmountOfActiveHighValueData(List<Data> dataList) {
    final int ACTIVE_STATUS = 1;
    final int HIGH_VALUE_THRESHOLD = 100;
    
    int totalAmount = 0;
    for (Data dataItem : dataList) {
        if (isActive(dataItem) && isHighValue(dataItem)) {
            totalAmount += dataItem.getValue();
        }
    }
    // ...
}

private boolean isActive(Data data) {
    return data.getStatus() == ACTIVE_STATUS;
}

private boolean isHighValue(Data data) {
    return data.getValue() > HIGH_VALUE_THRESHOLD;
}

• 함수의 이름 calculateTotalAmountOfActiveHighValueData는 이 함수가 하는 일을 명확하게 설명합니다.
• 변수명 dataList, totalAmount, dataItem은 각 변수의 역할을 분명히 보여줍니다.
• 복잡한 조건문은 isActive, isHighValue와 같이 의도를 드러내는 함수로 추출(Extract Method)하여 가독성을 극대화했습니다. 이제 코드는 “활성화 상태이고 고가인 데이터 항목에 대해 총합을 구한다”라고 소설처럼 자연스럽게 읽힙니다.

---

2. 단순성 (Simplicity): 복잡함은 적이다 (KISS 원칙)

핵심 아이디어: 가장 간단한 방법이 최고의 방법이다

소프트웨어 공학에는 “Keep It Simple, Stupid”라는 유명한 KISS 원칙이 있습니다. 이는 불필요한 복잡성을 최대한 배제하고, 가능한 한 가장 간단하고 명료한 방법으로 문제를 해결해야 한다는 원칙입니다. 개발자들은 종종 미래의 모든 가능성을 대비하기 위해 과도하게 복잡한 설계나 불필요한 기능을 미리 추가하려는 유혹에 빠집니다. (이를 YAGNI 원칙, “You Ain’t Gonna Need It” – 넌 그거 필요 없을 거야 – 위반이라고도 합니다.)

단순성은 코드의 양을 줄이고, 버그가 숨을 곳을 없애며, 시스템을 더 쉽게 이해하고 테스트할 수 있도록 만듭니다.

나쁜 코드: 불필요하게 복잡한 로직

Java

public String getUserRole(User user) {
    String role;
    if (user.getAuthLevel() == 0) {
        role = "GUEST";
    } else if (user.getAuthLevel() == 1) {
        if (user.isEmailVerified()) {
            role = "MEMBER";
        } else {
            role = "GUEST";
        }
    } else if (user.getAuthLevel() == 9) {
        if (user.isSuperUser()) {
            role = "ADMIN";
        } else if (user.isEmailVerified()) {
            role = "MEMBER";
        } else {
            role = "GUEST";
        }
    } else {
        role = "GUEST";
    }
    return role;
}

• if-else가 복잡하게 중첩되어 있고, 동일한 로직(role = "GUEST")이 여러 곳에 흩어져 있어 흐름을 파악하기 어렵습니다.

클린 코드: 명료하고 간결한 로직

Java

public String getUserRole(User user) {
    if (user.getAuthLevel() == 9 && user.isSuperUser()) {
        return "ADMIN";
    }
    if (user.getAuthLevel() >= 1 && user.isEmailVerified()) {
        return "MEMBER";
    }
    return "GUEST"; // 기본값 처리
}

• 가장 특수한 경우(ADMIN)부터 먼저 처리하고, 일반적인 경우(MEMBER), 그리고 기본값(GUEST) 순으로 처리하는 ‘가드 클로즈(Guard Clauses)’ 패턴을 사용하여 중첩을 완전히 제거했습니다.
• 코드가 훨씬 짧아졌을 뿐만 아니라, 각 역할(Role)이 어떤 조건에 의해 결정되는지 한눈에 명확하게 파악할 수 있습니다. 이것이 바로 단순성의 힘입니다.

---

3. 의존성 최소화 (Minimizing Dependencies): 홀로 설 수 있는 코드

핵심 아이디어: 코드는 최대한 독립적이어야 한다 (느슨한 결합)

좋은 코드는 다른 부분의 코드에 대한 의존성(Dependency)이 낮아야 합니다. 이를 ‘느슨한 결합(Loose Coupling)’이라고 합니다. 어떤 모듈이 다른 모듈의 내부 구현 방식에 대해 너무 많이 알고 있다면, 그 다른 모듈이 조금만 변경되어도 의존하고 있던 모듈까지 연쇄적으로 수정해야 하는 ‘수정 폭포’ 현상이 발생합니다.

의존성을 최소화하면 코드의 재사용성이 높아지고, 테스트하기 쉬워지며, 유지보수가 용이해집니다. 이를 위한 대표적인 기법이 바로 **의존성 주입(Dependency Injection, DI)**입니다.

나쁜 코드: 내부에 구체적인 구현을 생성하는 강한 결합

Java

public class ReportGenerator {
    private ExcelExporter exporter;

    public ReportGenerator() {
        // ReportGenerator가 ExcelExporter라는 구체적인 클래스를 '직접' 생성
        this.exporter = new ExcelExporter(); 
    }

    public void generateReport(Data data) {
        // ... 데이터를 가공하는 로직 ...
        exporter.exportToExcel(processedData);
    }
}

• 이 ReportGenerator는 ExcelExporter와 강하게 결합되어 있습니다. 만약 나중에 리포트를 PDF로도 내보내야 한다는 요구사항이 추가되면, ReportGenerator 클래스 자체의 코드를 수정해야만 합니다. 또한, 단위 테스트를 할 때마다 실제 엑셀 파일을 생성하는 ExcelExporter 때문에 테스트가 느리고 복잡해집니다.

클린 코드: 외부에서 의존성을 주입받는 느슨한 결합

Java

// 인터페이스 정의
public interface ReportExporter {
    void export(Data data);
}

// 구체적인 구현 클래스들
public class ExcelExporter implements ReportExporter { ... }
public class PdfExporter implements ReportExporter { ... }

// 의존성을 주입받는 클래스
public class ReportGenerator {
    private ReportExporter exporter;

    // 생성자를 통해 외부에서 '추상적인' 인터페이스를 주입받음
    public ReportGenerator(ReportExporter exporter) {
        this.exporter = exporter;
    }

    public void generateReport(Data data) {
        // ... 데이터를 가공하는 로직 ...
        exporter.export(processedData);
    }
}

// 사용하는 쪽 (Client Code)
ReportExporter excelExporter = new ExcelExporter();
ReportGenerator excelReport = new ReportGenerator(excelExporter); // 엑셀 리포트 생성기

ReportExporter pdfExporter = new PdfExporter();
ReportGenerator pdfReport = new ReportGenerator(pdfExporter); // PDF 리포트 생성기

• ReportGenerator는 이제 ReportExporter라는 ‘인터페이스(역할)’에만 의존할 뿐, 실제 구현이 엑셀인지 PDF인지는 전혀 알지 못합니다.
• 덕분에 새로운 내보내기 방식(예: CSV)이 추가되어도 ReportGenerator는 단 한 줄도 수정할 필요가 없습니다.
• 단위 테스트 시에는 실제 ExcelExporter 대신, 테스트용 가짜 객체인 ‘목(Mock) 객체’를 쉽게 주입하여 빠르고 고립된 테스트를 수행할 수 있습니다.

---

4. 중복성 제거 (Don’t Repeat Yourself, DRY)

핵심 아이디어: 모든 지식은 시스템 내에서 단 한 번만 나타나야 한다

DRY 원칙은 소프트웨어 개발에서 가장 유명하고 중요한 원칙 중 하나입니다. 이는 단순히 ‘코드를 복사-붙여넣기 하지 말라’는 것을 넘어, 동일한 로직이나 정보가 시스템의 여러 곳에 중복되어 표현되어서는 안 된다는 철학을 담고 있습니다. 코드의 중복은 유지보수의 악몽을 낳습니다. 만약 중복된 로직에 버그가 있거나 정책이 변경된다면, 해당 로직이 흩어져 있는 모든 곳을 찾아서 일일이 수정해야 하기 때문입니다. 하나라도 놓치면 시스템은 데이터 불일치와 예측 불가능한 버그로 가득 차게 될 것입니다.

나쁜 코드: 복사-붙여넣기의 폐해

Java

public void processManagerTask(Employee emp) {
    if (emp.getRole().equals("MANAGER")) {
        // 관리자 급여 계산 로직 (A)
        double baseSalary = emp.getBaseSalary();
        double bonus = baseSalary * 0.2;
        emp.setFinalSalary(baseSalary + bonus);
    }
}

public void calculateDirectorBonus(Employee emp) {
    if (emp.getRole().equals("DIRECTOR")) {
        // 관리자 급여 계산 로직과 사실상 동일 (A')
        double baseSalary = emp.getBaseSalary();
        double bonus = baseSalary * 0.2;
        emp.setDirectorBonus(bonus);
    }
}

• 관리자와 이사의 보너스 계산 로직(기본급의 20%)이 두 개의 다른 함수에 중복되어 있습니다. 만약 보너스 정책이 25%로 바뀐다면, 두 함수를 모두 찾아서 수정해야 합니다.

클린 코드: 중복을 제거하고 하나로 통합

Java

public void processManagerTask(Employee emp) {
    if (emp.getRole().equals("MANAGER")) {
        double salary = calculateSalaryWithBonus(emp.getBaseSalary(), 0.2);
        emp.setFinalSalary(salary);
    }
}

public void calculateDirectorBonus(Employee emp) {
    if (emp.getRole().equals("DIRECTOR")) {
        double bonus = calculateBonus(emp.getBaseSalary(), 0.2);
        emp.setDirectorBonus(bonus);
    }
}

// 중복 로직을 별도의 함수로 추출
private double calculateBonus(double baseSalary, double rate) {
    return baseSalary * rate;
}

private double calculateSalaryWithBonus(double baseSalary, double rate) {
    return baseSalary + calculateBonus(baseSalary, rate);
}

• 중복되던 보너스 계산 로직을 calculateBonus라는 하나의 함수로 추출했습니다. 이제 보너스 정책이 바뀌면 오직 이 함수 하나만 수정하면 됩니다.
• 모든 지식(보너스 계산법)이 시스템 내에서 단 한 곳에만 존재하게 되어, 코드의 신뢰성과 유지보수성이 크게 향상되었습니다.

---

5. 추상화 (Abstraction): 복잡한 내용은 숨기고 본질만 드러낸다

핵심 아이디어: 세부 구현이 아닌, ‘무엇을’ 하는지에 집중하게 하라

추상화는 복잡한 내부 구현의 세부 사항을 감추고, 사용자가 알아야 할 필수적인 기능(인터페이스)만을 노출하는 기법입니다. 이는 마치 우리가 자동차를 운전할 때, 엔진의 복잡한 내부 연소 과정을 전혀 몰라도 핸들, 페달, 기어라는 단순한 인터페이스만으로 자동차를 제어할 수 있는 것과 같습니다.

추상화를 통해 우리는 시스템을 더 작고, 독립적이며, 관리하기 쉬운 단위로 나눌 수 있습니다. 코드를 사용하는 쪽(Client)은 내부 구현이 어떻게 바뀌든 상관없이, 공개된 인터페이스만 그대로 사용하면 되므로 시스템의 유연성과 확장성이 크게 향상됩니다.

나쁜 코드: 구현의 세부 사항이 모두 노출된 코드

Java

public void sendNotification(User user, String message) {
    // 1. SMTP 서버 설정 가져오기
    String smtpServer = config.get("smtp.server");
    int smtpPort = Integer.parseInt(config.get("smtp.port"));
    
    // 2. 이메일 라이브러리를 사용하여 직접 연결
    EmailConnection connection = new EmailConnection(smtpServer, smtpPort);
    connection.connect();
    
    // 3. 이메일 형식에 맞춰 메시지 생성 및 전송
    String formattedEmail = "To: " + user.getEmail() + "... Body: " + message;
    connection.sendRaw(formattedEmail);
    
    connection.disconnect();
}

• 알림을 보내는 sendNotification 함수가 SMTP 서버 연결, 이메일 형식 생성 등 이메일 전송의 모든 ‘세부 구현’을 알고 있고 직접 처리하고 있습니다. 만약 알림 방식이 이메일에서 SMS나 푸시 알림으로 바뀐다면 이 함수는 완전히 새로 작성되어야 합니다.

클린 코드: 추상화 계층을 통해 구현을 숨긴 코드

Java

// 알림 서비스 인터페이스
public interface NotificationService {
    void send(User user, String message);
}

// 이메일 구현체
public class EmailService implements NotificationService {
    public void send(User user, String message) {
        // SMTP 연결 및 이메일 전송의 복잡한 로직은 여기에 숨겨져 있음
    }
}

// SMS 구현체
public class SmsService implements NotificationService {
    public void send(User user, String message) {
        // SMS 게이트웨이 연동 로직은 여기에 숨겨져 있음
    }
}

// 사용하는 쪽 (Client Code)
public class OrderProcessor {
    private NotificationService notificationService;

    public OrderProcessor(NotificationService notificationService) {
        this.notificationService = notificationService;
    }
    
    public void process() {
        // ... 주문 처리 로직 ...
        // '어떻게' 보내는지는 모르고, '보낸다'는 사실에만 집중
        notificationService.send(user, "주문이 완료되었습니다.");
    }
}

• OrderProcessor는 이제 NotificationService라는 ‘추상화’된 인터페이스에만 의존합니다. 이 서비스의 실제 구현이 EmailService인지 SmsService인지는 외부에서 주입해주기 나름입니다.
• 알림 방식이 어떻게 바뀌거나 추가되더라도, OrderProcessor의 코드는 전혀 변경할 필요가 없습니다. 이것이 바로 추상화를 통해 얻는 유연함과 확장성입니다.

---

마무리: 클린 코드는 전문가의 길

클린 코드는 단순히 코딩 스타일이나 기교의 문제가 아닙니다. 그것은 동료 개발자에 대한 배려이자, 미래의 나 자신을 위한 가장 현명한 투자이며, 프로 개발자로서 가져야 할 가장 중요한 책임감의 표현입니다.

오늘 살펴본 가독성, 단순성, 의존성 최소화, 중복성 제거, 추상화라는 5가지 원칙은 서로 독립적인 것이 아니라, 하나의 목표, 즉 ‘이해하고 유지보수하기 쉬운 코드’를 향해 유기적으로 연결되어 있습니다. 의미 있는 이름을 짓는 노력은 가독성을 높이고, 함수를 작게 나누는 것은 단순성과 중복성 제거에 기여하며, 추상화와 의존성 주입은 의존성을 낮추는 동시에 시스템 전체의 유연성을 확보합니다.

클린 코드를 작성하는 능력은 하루아침에 얻어지지 않습니다. 꾸준히 좋은 코드를 읽고, 자신의 코드를 비판적으로 바라보며, 동료들과의 코드 리뷰를 통해 끊임없이 개선해 나가는 ‘수련’의 과정이 필요합니다. 이 길은 결코 쉽지 않지만, 이 원칙들을 나침반 삼아 꾸준히 나아간다면, 여러분은 시간의 시험을 견뎌내는 견고하고 아름다운 코드를 만드는 진정한 장인(Craftsman)으로 인정받게 될 것입니다.