🧹 클린 코드 가이드: 유지보수하기 좋은 코드 작성법

✨ 오늘의 이야기

최근 코드 리팩토링을 하면서 '아, 이래서 클린 코드가 중요하구나?'를 온몸으로 깨닫게 되었습니다. 🤯

똑같은 기능을 하는데도 코드가 중복되어 있고, 변수명은 알아볼 수 없고, 함수 하나가 세 가지 일을 하고 있던 걸 보고… 결국 주말을 반납하고 블로그를 작성하기로 결심했습니다. 내가 고통받았던 만큼, 후배 개발자들은 좀 덜 고통받게 하자!

그래서 이번 글에서는 클린 코드의 핵심 원칙과 실천 방법을 위트 있게 정리해 보겠습니다. 🚀

---

1️⃣ 클린 코드란?

클린 코드란 읽기 쉽고, 이해하기 쉬우며, 유지보수가 용이한 코드를 의미합니다. 클린 코드의 목표는 단순히 동작하는 코드가 아니라, 다른 개발자가 쉽게 이해하고 수정할 수 있는 코드를 작성하는 것입니다.

✅ 클린 코드의 특징

• 가독성이 높다: 누구나 쉽게 읽고 이해할 수 있다.
• 중복이 없다(DRY 원칙): 동일한 코드를 반복해서 작성하지 않는다.
• **하나의 책임(Single Responsibility Principle, SRP)**을 가진다.
• 테스트가 용이하다: 단위 테스트와 자동화 테스트를 쉽게 적용할 수 있다.

---

2️⃣ 클린 코드를 위한 핵심 원칙

🏷️ 1. 명확한 명명법 (Meaningful Naming)

이해하기 쉬운 변수명과 함수명을 사용하면 코드의 가독성이 높아지고 유지보수가 쉬워집니다. 협업할 때 변수와 함수명이 직관적이지 않다면? 이제부터 *"이 변수는 대체 뭐하는 녀석이지?"*라는 철학적 고민이 시작됩니다. 잘못된 네이밍은 코드 이해도를 떨어뜨리고, 개발자들이 불필요한 시간 동안 코드를 해석하는 데 집중하게 만듭니다.

따라서 명확하고 의미 있는 이름을 짓는 것은 단순한 스타일 문제가 아니라, 협업과 유지보수를 위한 생존 전략입니다.

• 읽기 좋은 코드가 유지보수도 쉽다: tempData 같은 모호한 변수명보다 userSessionData처럼 역할이 명확한 이름을 사용하세요.
• 줄임말은 되도록 피하자: usrInfo 같은 애매한 이름보다 userInformation이 가독성이 훨씬 좋습니다.
• 일관된 네이밍 컨벤션을 유지하자: getUserName(), fetchUserName(), retrieveUserName() 같은 혼돈의 카오스를 피하기 위해 팀 내 컨벤션을 정하고 따르는 것이 중요합니다.
• 불필요한 접두사는 제거하자: isBooleanFlag 같은 변수명보다는 isActive처럼 간결하고 명확한 이름을 사용하세요.

결론적으로, 좋은 네이밍은 개발자가 동료들에게 남기는 최고의 배려이자, 미래의 나 자신을 위한 보험입니다. 지금 당장은 사소해 보이더라도, 코드가 커질수록 이 차이는 어마어마하게 커집니다!

🚫 나쁜 예제:

int a = 5; // a가 무엇을 의미하는지 모호함
String str = "Hello"; // str보다 의미 있는 이름을 사용할 것

✅ 좋은 예제:

int maxRetryCount = 5;
String welcomeMessage = "Hello";

✔️ 실천 방법:

• 변수와 함수 이름은 역할을 명확하게 설명해야 한다.
• 줄임말을 피하고, 의미 있는 단어를 사용할 것.

---

🏗️ 2. 함수는 하나의 역할만 수행해야 한다 (Single Responsibility Principle, SRP)

하나의 함수가 여러 가지 일을 한다면? 이제부터 악몽이 시작됩니다. 함수가 이것저것 다 하려 하면 결국 '만능'이 아니라 '만신창이'가 됩니다. 유지보수할 때마다 어디를 수정해야 할지 헷갈리고, 변경할 때마다 의도치 않은 버그가 발생할 가능성이 커집니다. 게다가, 같은 로직을 또 다른 곳에서 사용하려 하면? 복사-붙여넣기의 향연이 펼쳐지면서 기술 부채가 쌓이기 시작합니다. 개발자는 더 이상 기능 추가보다 버그 수정과 코드 이해에 시간을 허비하게 되고, 결국 '이 코드 누가 짰냐?'라고 속으로 외치는 날이 오게 됩니다.

기억하세요! 함수는 꼭 필요한 일만 해야 합니다. 하나의 함수가 하나의 역할을 수행하게 만들면, 코드가 더 읽기 쉬워지고 유지보수도 편리해집니다. 그리고 무엇보다도, 미래의 당신이 코드를 보며 한숨 쉬지 않게 됩니다.

🚫 나쁜 예제:

public void processOrder(Order order) {
    validateOrder(order);
    saveToDatabase(order);
    sendConfirmationEmail(order);
}

✅ 좋은 예제:

public void validateOrder(Order order) { /* 유효성 검사 */ }
public void saveToDatabase(Order order) { /* 데이터 저장 */ }
public void sendConfirmationEmail(Order order) { /* 이메일 전송 */ }

✔️ 실천 방법:

• 하나의 함수는 하나의 역할만 수행하도록 분리할 것.
• 여러 작업을 수행하는 경우 개별 함수로 분리하여 재사용성을 높인다.

---

📌 3. 중복을 제거하라 (Don't Repeat Yourself, DRY)

너무나 당연한 이야기지만, 중복된 코드가 많으면 유지보수가 어려운 것은 불 보듯 뻔한 일입니다. 최근 사용자 알림 기능을 리팩토링하다가 동일한 Java 코드가 두 벌씩 존재하는 것을 발견했는데, 푸시와 알림의 내용이 동일함에도 불구하고 코드가 이중으로 존재했습니다. 이렇게 되면 한쪽만 수정하고 다른 쪽은 수정하지 않는 실수가 발생할 가능성이 높아지고, 기능이 추가될 때마다 두 곳을 모두 수정해야 하는 번거로움이 생깁니다.

그리고, 만약 QA 단계에서 한쪽만 수정되었다면? 이제부터 코드의 이완화가 시작됩니다. 더 끔찍한 것은 이런 실수들이 누적되면서 코드의 일관성이 무너지고, 결국 유지보수 비용이 눈덩이처럼 불어날 수 있다는 점입니다. 반드시 명심합시다: 중복 코드는 유지보수의 적이며, 기술 부채의 지름길입니다!

🚫 나쁜 예제:

int sum1 = a + b + c;
int sum2 = x + y + z;

✅ 좋은 예제:

public int calculateSum(int... numbers) {
    return Arrays.stream(numbers).sum();
}

✔️ 실천 방법:

• 동일한 기능을 하는 코드가 반복되면 메서드로 추출한다.
• 공통 기능은 유틸리티 클래스로 관리한다.

---

💡 4. 주석은 필요한 곳에만 작성하라 (Write Self-Explanatory Code)

나의 예전 선임 시니어분께서 이렇게 말씀하셨다: "주석을 다는 것도 좋지만, 네 코드가 주석 없이도 이해될 만큼 명확한 것이 더 중요하다." 그리고 시간이 지나면서 이 말이 얼마나 현실적인 조언인지 깨닫게 되었다.

실무에서는 코드가 업데이트될 때마다 주석을 갱신하는 일이 쉽지 않다. 그렇다 보니 오래된 주석이 코드와 맞지 않는 경우가 빈번하고, 결국 '주석을 믿느냐, 코드를 믿느냐'라는 철학적 질문에 직면하게 된다. 가장 좋은 해결책은? 주석이 필요 없을 정도로 명확한 코드를 작성하는 것!

하지만, 때때로 불가피하게 복잡한 로직이 존재할 수 있다. 이럴 때는 JavaDoc을 활용하는 것이 좋은 방법이다. JavaDoc을 사용하면 코드가 업데이트될 때 함께 문서화할 수 있고, 유지보수도 한결 편해진다. 결국, 코드는 읽기 쉽게, 주석은 유지보수 가능하게! 이

두 가지 원칙을 기억하자.

🚫 나쁜 예제:

// 사용자의 이름을 가져옴
String name = user.getName();

✅ 좋은 예제:

String userName = user.getName(); // 특정한 로직이 있는 경우에만 주석을 추가

✔️ 실천 방법:

• 코드 자체로 의미가 명확하면 주석을 줄일 것.
• 로직이 복잡한 경우 주석을 추가하여 의도를 설명할 것.

---

🚀 5. 에러 처리를 제대로 하라 (Proper Exception Handling)

예외 처리는 코드의 안정성을 높이는 가장 중요한 요소 중 하나입니다. 운영 환경에서는 예외가 발생하는 것이 불가피하며, 이는 개발자가 통제할 수 없는 외부 API 호출 실패, 네트워크 문제, 사용자 입력 오류 등 다양한 이유로 발생할 수 있습니다. 하지만 예외를 어떻게 처리하느냐에 따라 서비스의 신뢰성과 유지보수성이 크게 달라집니다.

예외 처리를 명확하게 하면:

• 빠른 문제 해결: 적절한 예외 메시지를 제공하여 디버깅 시간을 단축하고, 문제의 원인을 한눈에 파악할 수 있습니다.
• 안정적인 운영: 예상치 못한 오류가 발생해도 시스템이 중단되지 않고 정상적으로 복구될 수 있습니다. 사용자가 장애를 겪지 않고 연속적인 서비스를 받을 수 있도록 하는 것이 핵심입니다.
• 개발 생산성 향상: 로그와 예외 처리가 체계적으로 정리되어 있으면, 새로운 개발자가 코드의 흐름을 쉽게 이해할 수 있으며, 문제 발생 시 원인을 빠르게 추적할 수 있습니다.

반면, 예외 처리가 불명확하면:

• 디버깅이 어려워진다: "Something went wrong" 같은 애매한 오류 메시지로 인해 문제의 원인을 추적하는 데 오랜 시간이 걸립니다.
• 운영 환경에서 혼란을 초래한다: 제대로 로깅되지 않은 예외는 운영팀에게 불필요한 혼란을 초래하고, 장애 발생 시 신속한 대응이 어려워집니다.
• 서비스 장애로 이어질 수 있다: 특정 예외가 적절하게 처리되지 않으면, 단순한 오류가 전체 서비스의 다운타임으로 이어질 수도 있습니다.

결론적으로, 예외 처리는 단순히 try-catch 블록을 넣는 것이 아니라, 발생할 수 있는 모든 예외를 예상하고, 적절한 대응 전략을 수립하는 것이 핵심입니다. 예외 처리를 잘하는 개발자는 운영 환경에서도 신뢰받는 개발자가 될 수 있습니다. 🚀

🚫 나쁜 예제:

try {
    int result = 10 / 0;
} catch (Exception e) {
    // 빈 catch 블록
}

✅ 좋은 예제:

try {
    int result = 10 / 0;
} catch (ArithmeticException e) {
    System.err.println("0으로 나눌 수 없습니다: " + e.getMessage());
}

✔️ 실천 방법:

• 예외 처리를 구체적으로 한다 (모든 예외를 Exception으로 처리하지 말 것).
• 로그를 남겨 문제를 추적할 수 있도록 한다.

---

🎯 마무리

클린 코드는 단순한 스타일 가이드가 아니라, 유지보수와 확장성을 고려한 개발 원칙입니다. 좋은 코드 습관을 기르면 개발 속도뿐만 아니라 협업 과정에서도 많은 이점을 얻을 수 있습니다.

📌 요약

✔ 명확한 변수명과 함수명을 사용하라.
✔ 하나의 함수는 하나의 역할만 수행하도록 하라.
✔ 중복을 제거하고 재사용성을 높여라.
✔ 코드를 읽기 쉽도록 주석을 최소화하라.
✔ 에러 처리를 명확히 하고, 안정적인 프로그램을 만들라.

최소한 위 5가지는 꼭 지키면서 코딩합시다!
이제부터 클린 코드를 작성하는 습관을 기르고, 더 나은 개발자가 되어 봅시다! ✨