개발자가 자주 하는 실수! 나쁜 코드의 징후와 해결 방법

• 개발자가 직접 작성한 코드조차 이해하기 어려울 때가 있음
• 깔끔하고 유지보수하기 쉬운 코드를 작성하는 것이 중요
• 나쁜 코드의 원인과 해결책을 알아보는 것이 필요

 

개발하면서 "이 코드 도대체 누가 짰어?" 하고 생각해본 적 있나요? 그런데 그 코드, 사실 내가 짠 거라면? 그 순간 머리를 감싸쥐고 한숨이 나올지도 몰라요. 누구나 깔끔하고 유지보수하기 쉬운 코드를 짜고 싶지만, 현실은 종종 다릅니다. 오늘은 내가 내 코드를 이해 못하는 이유와, 그런 일을 피하는 방법에 대해 이야기해볼게요.

 

개발자가 자주 하는 실수! 나쁜 코드의 징후와 해결 방법

 

징후 #1: 내 코드인데 찾을 수가 없다

한 번이라도 이런 경험 해보셨죠? "어제 분명히 여기다 넣었는데, 어디 갔지...?" 원하는 기능을 찾으려고 몇 분 이상 헤매고 있다면, 코드 구조가 엉망일 가능성이 커요.

 

왜 이런 일이 생길까요?

• 정리가 안 됐어요: 기능이 여기저기 흩어져 있어서 어디서 뭘 찾아야 할지 감이 안 옴
• 이름이 이상해요: x, data1, funcA 같은 애매한 변수명 때문에 혼란스러움
• 너무 복잡해요: 계층이 지나치게 많아서 코드 흐름을 따라가기 힘듦
• 문서화가 부족해요: 주석도 없고, README도 없다면 미래의 나 자신에게 재앙

 

실제 경험담

• 초보 개발 시절, 코드 구조가 엉망이라 원하는 기능을 찾기 어려웠음
• 코드가 객체로 나뉘어 있었지만 전체적인 틀 없이 분산됨
• 결국 간단한 코드 하나 찾는 데만 5분 이상 소요됨

 

개발을 시작한 지 얼마 안 됐을 때, 이미지 공유 사이트를 만들고 있었어요. 하루는 비밀번호 재설정 기능을 수정하려고 IDE를 열었는데, 어제 작성한 코드가 도대체 어디에 있는지 감도 안 잡히더라고요. 객체로 잘 나눠놓긴 했지만, 전체적인 틀 없이 여기저기 나눠져 있어서 결국 필요한 코드 하나 찾는 데 5분이 넘게 걸렸어요. 그런 순간, 진짜 멘붕 옵니다.

 

해결 방법

1. 파일을 논리적으로 정리하기
   • /controllers, /models, /views 같은 폴더 구조로 정리
2. 변수명과 함수명을 명확하게
   • tmpData 같은 의미 없는 이름 대신 userInput 같은 직관적인 이름 사용
3. 주석과 문서화를 신경 쓰기
   • README.md를 최신 상태로 유지하고, 중요한 부분에는 꼭 주석 남기기
4. 일관된 코딩 스타일 유지하기
   • Python이면 PEP 8, JavaScript면 Google Style Guide 같은 표준을 따르기

 

이렇게 하면 코드 찾는 시간이 줄어들고, 개발 속도도 빨라집니다.

 

징후 #2: 찾았는데도 무슨 뜻인지 모르겠다

간신히 코드를 찾아냈다고 끝이 아닙니다. 이제 문제는 그 코드가 무슨 의미인지 이해하는 데 또 시간이 걸린다는 거죠. "이걸 왜 이렇게 짰지...?" 하는 생각이 든다면, 가독성이 엉망인 겁니다.

 

이런 코드, 왜 이렇게 된 걸까요?

• 너무 꼬여 있어요: 함수가 여기저기서 데이터를 끌어와서 어디서 무슨 일이 벌어지는지 한눈에 안 보임
• 이름이 너무 애매해요: val, tmp, data 같은 이름은 혼란만 가중시킴
• 조건문과 반복문이 지나치게 많아요: 중첩된 if 문과 반복문이 많으면 흐름을 따라가기 힘듦
• 주석이 없어요: 코드에 대한 설명이 없으면 나중에 봤을 때 "이게 뭐지?" 하게 됨
• 쓸데없이 복잡한 추상화: 굳이 여러 계층으로 나누지 않아도 될 걸 나눠서 더 어렵게 만들어버림

 

코드 예제 비교

• 코드가 이해하기 어려운 이유는 변수명이 모호하고 구조가 복잡하기 때문
• 의미 있는 변수명을 사용하면 가독성이 크게 향상됨
• 작은 개선만으로도 코드 이해도가 높아짐

 

이런 코드, 이해하기 쉽나요?

def calc_r(x, y, z, a, b):
    return ((x * y) + (z * a) - b) / (y + a)

 

솔직히 뭐 하는 함수인지 모르겠죠? 하지만 이렇게 바꾸면 어떨까요?

def calculate_user_ranking(likes, shares, comments, views, penalties):
    return ((likes * shares) + (comments * views) - penalties) / (shares + views)

 

이제야 뭘 하는 함수인지 한눈에 보이죠? 변수 이름만 바꿔도 가독성이 확 올라갑니다.

 

어떻게 개선할까요?

1. 큰 함수는 쪼개기
   • 여러 가지 역할을 하는 거대한 함수보다는, 작은 단위로 나눠서 재사용성을 높이기
2. 명확한 변수명 사용하기
   • data1 같은 의미 없는 이름 대신 userLikes처럼 직관적인 이름으로 변경
3. 하나의 함수는 하나의 역할만 하도록 만들기
   • 단일 책임 원칙(SRP)을 적용해서 이해하기 쉽게 만들기
4. 주석과 문서화 적극 활용하기
   • 중요한 부분에는 설명을 추가해서 코드 흐름이 한눈에 보이도록 하기
5. 불필요한 추상화 피하기
   • 지나치게 많은 계층을 나누지 않고, 필요한 만큼만 분리하기

 

이렇게 하면 미래의 나 자신도 쉽게 이해할 수 있는 코드가 완성됩니다.

 

마무리

• 코드가 지저분하면 유지보수가 어렵고 개발자에게 부담
• 처음부터 가독성이 좋은 코드를 작성하면 장기적으로 큰 도움

 

지저분한 코드는 단순히 보기 안 좋은 걸 넘어서, 시간을 낭비하고 개발자를 지치게 만들어요. 처음부터 깨끗한 코드를 작성하는 습관을 들이면, 나중에 두 배, 세 배 편해집니다.

 

간단한 해결 방법

✅ 코드 구조 정리 ✅ 직관적인 변수 및 함수명 사용 ✅ 주석과 문서화 추가 ✅ 모듈화된 코드 작성 ✅ 불필요한 복잡성 줄이기

이 원칙들을 따르면 코드 짜는 게 훨씬 즐거워질 거예요. 자, 이제 깔끔한 코드 작성하러 가볼까요? 🚀