좋은 코드란 무엇인가? : “깔끔함”보다 중요한 기준들

 

개발을 조금만 해보면 “좋은 코드”라는 말을 정말 자주 듣습니다. 그런데 막상 “좋은 코드가 뭐예요?”라고 물으면 답이 제각각입니다. 누군가는 짧은 코드를 말하고, 누군가는 성능 좋은 코드를 말하고, 또 누군가는 예쁜 구조를 말합니다. 결국 이 질문은 취향 싸움처럼 보이기도 합니다.

실무에서는 분위기가 조금 다릅니다. 코드가 예뻐 보이는지보다, 팀이 안전하게 운영하고 계속 바꿀 수 있는지가 더 중요하게 취급됩니다. 서비스는 계속 바뀌고, 요구사항은 매주 업데이트되고, 장애는 가끔이라도 반드시 옵니다. 그래서 좋은 코드는 “내가 만족하는 코드”가 아니라 “팀이 오래 버틸 수 있는 코드”에 더 가깝습니다.

 

 

 

 

실무에서 좋은 코드의 1번 조건은 ‘다른 사람이 바로 이해하는가’입니다

현장에서 코드는 혼자 쓰고 끝나는 글이 아닙니다. 내가 만든 코드는 다음 달의 내가 다시 만지기도 하고, 팀원이 이어받기도 하고, 급한 장애 상황에서 누군가가 새벽에 들여다보기도 합니다. 그 순간에 “이게 무슨 의도지?”가 나오면 시간이 순식간에 새어 나갑니다.

그래서 좋은 코드는 읽기 쉬운 코드에서 시작합니다. 여기서 말하는 “읽기 쉬움”은 주석을 많이 달라는 뜻이 아닙니다. 함수 이름과 변수 이름만 보고도 흐름이 보이고, 조건문이 복잡하게 꼬이지 않고, 한 파일이 과하게 거대하지 않은 상태를 말합니다. 코드가 읽히면 리뷰가 쉬워지고, 리뷰가 쉬우면 실수가 줄어듭니다. 결국 일정도 덜 흔들립니다.

실무에서 읽기 쉬움을 만드는 습관

• 함수는 “무엇을 하는지”가 이름으로 드러나게 만들기
• 조건문은 조기 반환(early return)으로 깊이를 줄이기
• 한 함수에서 역할을 너무 많이 하지 않게 쪼개기
• 불필요한 축약어/애매한 이름 피하기(특히 신규 합류자가 이해하기 어렵습니다)

읽히는 코드가 결국 살아남습니다.

 

좋은 코드는 ‘변경하기 쉬운 코드’입니다

실무에서 개발이 힘든 이유는 새로운 기능을 만드는 것보다, 기존 기능을 건드릴 때 더 많이 터지기 때문입니다. 이미 운영 중인 기능은 사용자 행동, 데이터, 외부 연동, 권한 정책 같은 요소가 겹겹이 쌓여 있습니다. 여기서 작은 수정 하나가 다른 곳을 깨뜨리면, 팀은 불안해지고 배포는 무서워집니다.

그래서 좋은 코드의 중요한 기준은 변경 용이성입니다. 요구사항이 바뀌었을 때 “어디를 고치면 되는지”가 또렷하고, 수정 범위가 특정 모듈에 모여 있고, 수정이 다른 영역으로 새지 않는 구조가 좋습니다. 반대로 모든 로직이 한 파일에 뭉쳐 있거나, 여기저기 복사된 코드가 많으면 수정할 때마다 지뢰밭이 됩니다.

변경이 쉬운 코드가 가진 공통점

• 중복이 적고 공통 로직이 한 곳에 모여 있습니다
• 의존성이 적절히 분리되어 있어 영향 범위가 작습니다
• 입력과 출력이 명확해 “이 함수는 이 일만 한다”가 보입니다

바꿀 수 있어야 유지됩니다.

 

실무에서 진짜 중요한 건 ‘예외 처리와 실패 흐름’입니다

데모 환경에서는 늘 성공 케이스만 보여줍니다. 하지만 실서비스는 실패 케이스가 더 자주 등장합니다. 네트워크가 끊기고, 외부 API가 늦고, 사용자가 이상한 값을 넣고, 권한이 없는 요청이 들어옵니다. 이때 코드가 “정상 흐름만” 생각하고 있으면 장애로 이어질 가능성이 커집니다.

그래서 좋은 코드는 실패했을 때도 예측 가능한 동작을 합니다. 에러 메시지가 의미 있게 남고, 어디서 실패했는지 로그로 추적이 가능하고, 사용자에게는 적절한 안내가 나갑니다. 반대로 예외를 묵살하거나(빈 catch), 실패해도 무조건 성공처럼 응답해버리면 문제는 더 큰 비용으로 돌아옵니다. 운영팀과 CS가 “왜 안 됐는지”를 모르게 되는 순간부터 복구 시간이 늘어납니다.

실패 흐름에서 자주 챙기는 포인트

• 예외를 잡되, 원인 파악이 가능하도록 로그/메시지 남기기
• 재시도 정책은 무작정 늘리지 말고(폭주 위험) 조건을 명확히 하기
• 사용자에게는 “다시 시도/문의” 등 다음 행동이 보이게 안내하기

실패를 다루는 방식이 품질을 결정합니다.

 

테스트 가능한 코드가 좋은 코드로 평가받는 이유

좋은 코드 이야기를 하다 보면 “테스트”가 꼭 따라옵니다. 이유는 간단합니다. 테스트가 있으면 팀이 더 대담하게 바꿀 수 있기 때문입니다. 기능을 고쳐도 자동 테스트가 빨리 실패를 알려주면, 문제를 초기에 막을 확률이 높아집니다. 반대로 테스트가 없으면 매번 수동으로 확인해야 하고, 그 과정에서 놓치는 구간이 생깁니다.

다만 테스트를 많이 만든다고 무조건 좋은 건 아닙니다. 유지하기 어려운 테스트는 오히려 발목을 잡기도 합니다. 실무에서는 “자주 깨지는 구간”, “장애로 이어지면 큰 구간”, “결제/권한/정산처럼 민감한 구간”부터 테스트를 붙이는 쪽이 현실적입니다. 이런 영역에 테스트가 잘 붙어 있으면 좋은 코드라는 평가를 받는 경우가 많습니다. 팀이 안정감을 느끼니까요.

 

성능은 ‘빠른 코드’보다 ‘문제를 일으키지 않는 코드’가 먼저입니다

초보자일수록 좋은 코드를 “무조건 빠른 코드”로 생각하기 쉽습니다. 그런데 실무에서 성능은 상황에 따라 다룹니다. 대부분의 기능은 극한 최적화보다 안정적인 구조가 더 중요하고, 정말로 병목이 되는 구간은 전체의 일부인 경우가 많습니다.

실무에서는 대체로 이런 순서로 판단합니다. 먼저 정확하게 동작하는가, 다음으로 운영 중 장애를 만들지 않는가, 그 다음에 “지표로 확인된 병목”을 최적화합니다. 근거 없이 미리 최적화하면 코드가 복잡해지고, 그 복잡함이 유지보수 비용으로 돌아오기 쉽습니다. 그래서 좋은 코드는 성능을 무시하는 게 아니라, “측정하고 필요한 곳만 고친다”는 태도를 갖고 있습니다.

성능 개선이 자연스러운 팀의 공통점

• 느려진다는 말이 나오면 로그/지표로 먼저 확인합니다
• 병목이 확실한 곳부터 개선합니다
• 개선 후에도 다시 측정해 효과를 확인합니다

빠름은 근거에서 나옵니다.

 

코드 스타일보다 더 중요한 건 ‘팀 규칙을 지키는가’입니다

코드 리뷰에서 “이렇게 써야 한다”는 의견이 오갈 때, 종종 감정이 섞입니다. 그런데 실무에서 좋은 팀은 논쟁을 줄이기 위해 규칙을 먼저 세웁니다. 포맷터(자동 정렬), 린터(규칙 검사), 코드 리뷰 체크리스트 같은 것들이죠.

이 규칙이 있으면 좋은 점이 있습니다. 개인의 취향이 아니라 팀의 기준으로 이야기할 수 있습니다. 리뷰 시간이 줄고, 불필요한 말싸움이 줄고, 코드 품질이 일정 수준으로 유지됩니다. 그 결과 “특정 사람만 잘 아는 코드”가 줄어드는 방향으로 갑니다. 이런 환경에서 만들어진 좋은 코드는 개인기가 아니라 팀 문화의 산물인 경우가 많습니다.

 

운영 관점에서 보면 좋은 코드는 ‘문제가 생겼을 때 빨리 찾을 수 있는 코드’입니다

운영 중 문제가 생겼을 때 가장 무서운 건 “원인을 못 찾는 상태”입니다. 같은 에러가 나는데도 어디서 터지는지 모르고, 사용자마다 증상이 다르고, 로그가 부족하고, 배포 이력도 애매하면 복구 시간이 길어집니다.

그래서 실무에서 좋은 코드는 관찰 가능성을 갖춥니다. 적절한 로그, 의미 있는 에러 코드, 요청을 추적할 수 있는 식별자, 그리고 장애 시 임시로 기능을 끌 수 있는 스위치(기능 플래그)가 있으면 대응이 쉬워집니다. 이런 것들이 “코드가 예쁘다”와는 별개로 현장에서 높은 평가를 받는 이유입니다. 운영은 늘 현실이니까요.

 

결국 좋은 코드는 ‘팀이 오래 안전하게 굴릴 수 있는 코드’입니다

정리하면, 실무에서 말하는 좋은 코드는 대체로 이런 특징을 갖습니다. 읽기 쉽고, 바꾸기 쉽고, 실패했을 때 흔들리지 않고, 테스트로 뒷받침되고, 운영 중 문제가 생겨도 빠르게 추적할 수 있습니다. 그리고 무엇보다 팀의 규칙 안에서 일관되게 작성됩니다.

코드는 시간이 지나면 반드시 손을 타게 됩니다. 그때도 버틸 수 있는 구조를 만들면 “좋은 코드”라는 말이 따라옵니다. 단기간에 완벽해질 필요는 없습니다. 다만 다음 수정이 더 쉬워지도록, 작은 기준을 지켜 쌓아가는 쪽이 실무에서는 훨씬 현실적입니다.

 

---

 

좋은 코드는 예쁜 코드가 아니라, 팀이 이해하고 바꾸고 운영할 수 있는 코드입니다. 오늘 만든 기능이 다음 달에도 안전하게 수정되고, 배포가 덜 무섭고, 장애 때 원인을 빨리 찾을 수 있다면 그게 실무에서 말하는 좋은 코드에 가깝습니다. 결국 코드는 사람을 위한 도구이고, 좋은 코드는 팀을 편하게 만듭니다.