---

# 서론 – “새벽 2시, 갑자기 온 페이지에 당황한다면?”

깊은 밤, 갑자기 전화가 울리고 “서비스가 다운됐어요!” 라는 알림이 뜨면 누구라도 당황하기 마련입니다. 특히 코드 가독성이 떨어진 프로젝트라면, 문제를 파악하고 해결하는 데 몇 시간을 허비하게 됩니다. 이번 포스트에서는 “Write code that you can understand when you get paged at 2am”이라는 유명한 개발자 격언을 바탕으로, 리팩터링과 디버깅을 쉽게 할 수 있는 실전 원칙 5가지를 소개합니다. 초보자도 바로 적용할 수 있도록 구체적인 예시와 체크리스트를 제공하니, 오늘부터 바로 실천해 보세요!

---

# 본론

# 1️⃣ 의미 있는 변수·함수 이름 짓기

핵심 포인트 : 이름만 보고도 역할이 파악돼야 합니다.

• 좋은 예 : calculateMonthlyInterest(amount, rate)

• 나쁜 예 : calc(a, b)

Tip: 한글도 충분히 사용해도 됩니다. 월이자계산(원금, 이율)처럼 직관적으로 적어 보세요.

# 2️⃣ 함수는 한 가지 일만! (Single Responsibility Principle)

한 함수에 여러 로직을 섞으면 새벽에 디버깅할 때 흐름을 추적하기 힘듭니다.

• 분리 전

python

  def process_order(order):

      validate(order)

      save_to_db(order)

      send_email(order)

• 분리 후

python

  def validate(order): ...

  def persist(order): ...

  def notify(order): ...

각 함수가 독립적이므로 어느 부분에서 오류가 났는지 바로 찾을 수 있습니다.

# 3️⃣ 주석·Docstring은 ‘왜’를 설명한다

코드 자체는 ‘무엇을’ 하는지 보여주지만, 왜 그런 선택을 했는지는 주석에 남겨야 합니다.

java

// 왜? – 현재 정책에 따라 할인율을 5% 고정

double discountRate = 0.05;

주석이 과다하면 오히려 방해가 되니, 핵심 로직에만 간결히 남기세요.

# 4️⃣ 일관된 코드 스타일 유지 (Lint & Formatter)

팀 전체가 같은 규칙을 쓰면, 새벽에 누가 작성했는지 몰라도 읽기 쉬워집니다.

• ESLint, Prettier, Black 같은 자동 포맷터를 CI에 연결

• 코드 스타일 가이드(예: Google Java Style) 를 프로젝트 루트에 README.md 로 남기기

# 5️⃣ 테스트 코드와 로그는 필수!

• 단위 테스트: 실패 원인을 바로 파악할 수 있는 가장 빠른 방법

• 구조화된 로그: 시간·레벨·컨텍스트를 포함해 JSON 형태로 남기면 검색이 쉬워집니다.

go

log.WithFields(logrus.Fields{

    'user_id': uid,

    'action':  'login',

}).Info('User login attempt')

---

# 결론 – 지금 바로 실천하고 새벽 페이지를 두려워하지 마세요!

1️⃣ 이름 짓기부터 시작해 보세요.

2️⃣ 함수 분리와 주석을 적용해 코드 흐름을 명확히 하세요.

3️⃣ 자동 포맷터와 테스트를 CI에 연결해 품질을 고정하세요.

새벽 2시에도 당황하지 않고 문제를 잡아낼 수 있다면, 당신은 이미 코드 가독성을 높이는 데 성공한 것입니다. 오늘 소개한 5가지 원칙을 하나씩 적용해 보며, “내 코드는 언제든 이해할 수 있다”는 자신감을 얻어 보세요.

행동 유도: 이 글이 도움이 되었다면, 깃허브에 README.md 로 정리한 “코드 가독성 체크리스트”를 공유하고, 팀원들과 함께 리뷰해 보세요. 여러분의 작은 실천이 프로젝트 전체의 안정성을 크게 높여줄 것입니다. 🚀