백엔드, 좋은 코드란 무엇일까? 클린코드?

 

 

좋은 코드가 도대체 뭐지?

‘좋은 코드란?‘이라고 구글링해보면 많은 검색 결과가 나온다. 나도 그렇고 다들 궁금했던듯하다. ‘좋은 코드’란 녀석은 정체도, 실체도 없이 이 세상에 떠돌고 있다. 모두가 ‘좋은 코드’의 기준이 조금씩 다르고 각각의 경험을 기반으로 좋은 코드를 정의하고 있다. 세간에 좋은 코드의 정의는 정말 많다.

• 읽기 쉬운 코드
• 중복이 없는 코드
• 테스트가 용이한 코드
• 등등…

 

읽기 쉬운 코드가 좋은 코드?

이 제목의 책도 있다. 제목 그대로의 내용을 담고 있고 읽기 쉬운 코드를 작성하기 위해서 지켜야 할 몇 가지를 제안하고 있다.

 

읽기 쉬우려면 주석을 쓰면 되지 않나?

단순하게 생각해서 읽기 쉽도록 코드를 작성하려면 작성자에게 익숙한 언어를 사용하면 된다. 한국인이라면 영어로 복잡하게 작성된 코드보다 한국어가 익숙하지 않을까? 모든 코드에 한국어로 주석을 상세히 작성해두면 코드를 읽지 않아도 코드가 무엇을 하는지 빠르고 쉽게 파악할 수 있다.

// 이름: 원리금상환
// 설명: 원리금상환을 처리하는 Mapper
// 인자1: m: 원리금
// 인자2: pe: 신용등급
public void refundMapper(int m, String pe){
	...
}

 

주석만 읽어봐도 언제 사용해야 하며 무엇을 함수의 인자로 전달하는지 알 수는 있다.

하지만 주석은 관리하기 어렵다. 주석은 기본적으로 메타데이터이기 때문에 주석의 내용과 함수의 실제 동작이 일치한다고 보장할 수 없다.

수시로 변하는 요구사항을 반영하느라 함수가 수정될 때 주석이 함께 수정되지 않을 수도 있다. 오히려 한두 가지의 잘못된 주석으로 코드를 이해하는데 혼란을 야기할 수 있다.

나한텐 읽기 쉬운데?

코드가 읽기 쉽도록 작성되어야 함은 너무나도 분명하다. 하지만 모든 개발자가 동일한 배경지식을 가진 것은 아니다. 각자 다른 환경에서 코드를 작성하고 읽기 때문에 ‘읽기 쉽다’는 것은 개개인에게 다르게 다가간다.

변수명을 잘 짓는다는 것도, 영어를 모국어로 사용하고 있지 않은 사람들에겐 다르게 다가간다. 어떤 누군가에겐 어색한 영어로 짓는 변수명이 잘 읽힐 수도 있기 때문에 잘 지은 변수명 또한 각자의 배경지식에 따라 기준이 모호하다.

또한 코드를 작성하는 시점에는 작성한 코드에 대한 이해가 100%이기 때문에 아무리 ‘읽기 쉽게’ 작성하고자 노력해도 한계가 있을 수밖에 없다.

읽기 쉬우면 끝인가?

읽기만 쉬우면 될까? 너무 원초적이고 당연한 이야기이기에 와 닿지 않는다. 읽기 쉽다는 것은 단순히 코드를 읽는 것만 의미하는 것이 아니라 이해하는 것까지 포함하기 때문에 나무뿐만 아니라 숲을 볼 때도 쉬워야 한다.

그보다 더 근본적인 이유, 좋은 코드가 읽기 쉬운 코드라면 왜 읽기 쉽도록 작성해야 하는가? 어떻게 읽기 쉽도록 작성하는가? 에 대한 물음으로 좋은 코드에 대한 정의를 다시 한번 생각해 볼 수 있다.

 

왜 읽기 쉬워야 하지?

중복이 없는 코드?

개발자라면 누구나 A와 B에서 동일한 로직을 수행하는 코드를 보는 순간, 공통으로 추출(extraction)하고 싶어 한다. 동일한 로직을 수행하는 코드가 여기에도 저기에도 있는 것은 굉장히 불편하기 때문이다.

 

이 불편함은 어디에서 오는 걸까?

 

오래전에 작성해둔 코드에서 A라는 코드 조각이 두 군데에 퍼져있다는 것을 기억하기 쉽지 않다. 때문에 한 곳의 A만 수정되었을 때 다른 한 곳에서 버그가 발생한다. 이러한 경험에 기반하여 동일한 로직을 수행하는 코드는 별도의 함수로 빼두고 재사용하려고 한다.

 

그 땐 같았지만 지금은 같지 않은

하지만 이렇게 공통으로 사용하고 있는 코드를 수정하는 건 어렵다. 분명 A라는 코드 조각을 동일한 로직을 수행하여 별도로 추출했지만, 시간이 지나고 A와의 조금 다른 A* 역할로 수정이 필요해졌다.

그때는 중복이었던 코드 조각을 필요에 의해 추출했지만, 지금은 아니라서 다시 합치거나 수정하고 있다. 보통 하는 일은 동일하지만, 그 목적이 다른 코드를 추출했을 때, 많이 발생하는데 이것은 변경 사항을 반영하는 데 비용이 들어가게 한다.

 

추출은 어떤 ‘기준’으로 해야할까?

 

왜 좋지 않은 코드가 생산되는가?

사실 우리는 코드를 작성할 시점에는 모두 좋은 코드를 작성하기 위해 노력한다. 그러나 이것을 놓치는 시점이 존재하고 좋지 않은 코드가 생산되는 것은 아닐까.

어쩌다가 코드가 상하게 되는걸까?

 

우리는 어떤 상황들을 마주하게 되는가?

개발자는 새로운 프로젝트를 만들기도 하지만 기존의 코드를 수정하기도 하고 다시 만들기도 한다. 그리고 새롭게 만든 프로젝트는 세상의 빛을 보기도 전에 수정될 가능성이 (매우) 많다.

• 이미 운영 중인 서비스의 CS 대응하며 수정하기
• 변경된 요구사항, 인터페이스를 반영하기
• 어제 또는 방금 작성한 코드 수정하기
• …

 

쓰이지 않는 코드

쓰지 않게 된 코드(Dead code)가 있는데, 이 코드가 어디에서 쓰일지도 모른다는 불안감이 있다면 감히 삭제하지 못할 것이고 이 코드는 깨진 유리창 중 하나가 된다.

 

이 불안감은 어디에서 오는 것일까?

 

 

1. 거리

코드가 동작하는 곳과 코드가 정의된 곳 간의 물리적 거리가 멀면 파악하기 힘들어진다. 보고 있는 코드가 일정 범위에서만 사용된다는 확신이 있다면 그 범위만 확인 후 사용하지 않는 코드라는 확신을 얻을 수 있다.

2. 순수하지 않은 함수

함수 외부의 어떤 값을 기반으로 동작하는 함수는 그 side effect를 제어하기 어렵다. 함수의 입출력만 확인하여 함수 내부를 수정할 수 없다면 수정하기 까다롭다.

public int getWage(name) {
  return this.getMySalary(name) / this.getTotalTime(new Date())
}

 

getWage란 함수는 name이라는 입력 외에도 getMySalary라는 입력으로 정의되지 않은 입력이 존재하며 new Date()라는 항상 변하는 값에 의존한다.

응급처치를 한 코드

중복으로 빼뒀지만 사용하는 곳에서 다른 로직을 추가해줘야 할 때를 종종 마주한다. 이 때 수정으로 인한 Side effect가 두려워 함수에 입력을 추가하던가 옵션 값을 추가하여 내부에서 억지로 처리할 때 그 코드는 좋지 않은 코드가 된다.

이렇게 응급처치가 몇 번 이뤄지면 누구도 알아보기 어려운 함수가 탄생한다. 당연히 이런 함수는 우리가 고민하는 좋은 코드라고 할 수 없다.

 

기술부채

응급처치가 무조건 나쁘다는 말이 아니다. 당장 문제 해결을 하는 데에 이만큼 빠른 대응이 없다. 현재 서비스에서 발생하는 버그를 잡아야 하는데, 전체적인 구조 리팩토링을 할 수 없기 때문이다. 다만 이런 응급처치한 코드들은 부채가 되고 상환의 의무를 져야 한다.

자금이 필요하여 은행에서 대출을 받았다면 대출받은 금액을 언젠가 상환해야 하는 것과 동일한 이치이다. 적절한 대출로 자금을 보다 융통성 있게 사용할 수 있다. 마찬가지로 잠시 기술 부채를 두고 문제를 해결하는 것도 중요하다. 과도한 대출은 이자의 부담이 심한 것처럼 기술 부채가 많아질수록 그 코드를 유지보수 하는데 더 큰 비용이 들어가기 때문에 적정선을 찾는 것 또한 중요하다.

 

좋지 않은 코드를 줄이기

좋지 않다고 생각되는 코드들을 살펴봤다. 좋은 코드란 좋지 않은 코드가 없는 코드를 말한다. 좋은 코드를 작성하려고 노력하는 대신 좋지 않은 코드를 줄여보자. 그리고 격리해보자. 작성된 모든 코드는 결국 유지 보수 비용이 필요하다. 궁극적으로 우리의 코드는 점진적으로 개선이 가능해야 한다.

 

추출이 아닌, 추상화

추출과 추상화는 무엇이 다를까?

 

추출(extraction)

‘추출하다(extract)‘의 어원을 살펴보면 ex(밖으로)와 tract(끌어내기)의 합성어이다. 특별한 기준없이 단순히 밖으로 끌어내는 것을 의미한다.

추상화(abstraction)

‘추상화하다(abstract)‘의 어원은 조금 다르다. ab(먼 개념)와 tract(이끌어내기)의 합성어로, 어떤 대상의 중요한 요점들을 재해석하여 정리한 것이라고 해석할 수 있다.

 

의존성을 드러내기 위한 추상화

우리가 별도 함수 또는 파일로 추출하는 이유는 여러 가지가 있다. 다른 곳에서 재사용하기 위해 분리하고 단지 파일이 커져서 분리한다. 단순히 중복된 코드 덩어리(chunk)에 대해 추출하면 재사용하기 어렵다. 오히려 함수 간 의존 관계를 파악하기 위해 비용이 들어가게 된다. 잘못 추출한 것이다.

함수를 분리할 때는 그 함수의 역할을 인지하고 하나의 역할만 하도록 정의해야 한다. 즉 의존성을 드러내기 위함이 추출의 목적이 되어야 한다.

한 파일에 여러 로직이 얽혀있을 때 각 코드 조각 중 서로 의존 관계에 있는 것들을 추출해야 한다. 이렇게 추상화가 된 함수는 하나의 목적(역할)을 갖게 되고 의미 있는 추출(추상화)이 이루어진다.

 

의존 관계가 있는 것들끼리 추상화를 해보자.

 

Where

무엇을 분리할지 알았다면 이제 어디에 분리할지 결정해야 한다.

단순히 컴포넌트를 렌더링하는 함수 컴포넌트일 경우, 어느 정도의 레벨로 공유될지에 따라 정의되는 위치가 달라진다. 어떤 함수는 도메인과 강하게 결합해 있어서 특정 페이지에서만 재사용될 수 있고 어떤 함수는 의존 관계없이 어디에서든 사용할 수 있다.

 

목적에 따라 맞는 위치에 정의해주는 것 또한 중요하다. 

삭제하기 쉬운 코드와 삭제하기 어려운 코드의 분리

아무리 깔끔한 코드를 작성해도 비즈니스 요구사항을 맞추다 보면 어쩔 수 없이 복잡한 코드가 작성된다. 사용하고 있는 라이브러리에서 발생한 버그일 수도 있고 여러 브라우저에 대응하다 탄생한 코드일 수 있다.

이런 코드는 제3자 입장에서 읽기도 어렵고 섣불리 삭제하기도 어렵다. 복잡한 요구 사항을 담고 있는 코드는 변경에 유연하지 못하기 때문에 별도로 분리해둬야 한다.

좋지 않은 코드가 생산되는 것을 완전히 차단할 수 없다면 제대로 관리될 수 있도록 격리해야 한다.

위에서 코드의 맥락을 이해하는 데 방해가 될 수 있는 요소 중 하나로 주석을 이야기했지만, 이 경우엔 주석과 함께 격리해두면 기존 코드의 흐름을 끊지 않고 복잡한 코드를 이해하는데 도움을 줄 수 있다.

@Component
public class CommitUtil {

    private GitHub github;

    @Value("${github.token}")
    private String token;
}

하드코딩이 불가피한 경우, 비즈니스 요구사항이 복잡하여 hacky한 코드를 작성해야 하는 경우 등 어쩔 수 없이 좋지 않게 작성되는 코드들은 주석과 함께 격리시켜 관리할 수 있다. 또한 설정 값으로 분리하여 application.properties에서 설정값을 관리하고 자바 파일에 주입하여 사용하는 방법을 고려하자.

일관성 있는 코드

최소한의 가독성을 보장하는 방법은 일관성 있는 코드를 작성하는 것이다. 일관성은 합의된 규칙을 기반으로 만들어지며 이 합의된 규칙은 개개인에게 동일하게 다가간다.

코드에 일관성이 지켜진다면 예측이 가능하다. 예측이 가능하다는 것은 어느 곳에 어떤 코드가 위치하는지 예상할 수 있다는 것이다. 프로젝트 팀원 간의 그라운드 룰(Ground Rule)이 필요한 이유이다.

 

Naming

변수명 네이밍도 중요하지만 작성되는 수많은 함수의 네이밍에도 규칙이 있으면 일관성을 지킬 수 있다.

// Case 1.
// prefix: 
// action: Regist
// target: kyc
public Wallet RegistKyc(){
	...
}

위와 같이 prefix, action, target 이 일관된 규칙으로 작성되면 함수를 파악하는데 큰 도움이 된다.

 

Directory

디렉터리 구조는 위에서 말한 ‘어디에 분리할지’와 관련이 있다.

우선 디렉터리 구조와 아키텍처는 비교 대상이 아니다. (아키텍처 !== 디렉터리 구조) 일관된 디렉터리 구조는 전체적인 구조를 파악하는 데 큰 도움이 되고 컴포넌트 간의 관계를 파악하는데에도 도움을 준다.

Top Level의 directory 구성에 따라 어느 곳에 어떤 모듈 또는 컴포넌트들이 위치할지 예측이 된다면 코드를 빠르게 이해할 수 있다.

프론트를 예로 들자면 다음과 같을 것이다.

src
├── api
├── components
├── hooks
├── model
├── pages
│   ├── contract
│   └── docs
└── utils

 

components 디렉터리라면 디렉터리 구조가 컴포넌트 hierarchy를 드러낼 수 있고 pages 디렉터리라면 route path를 드러낼 수 있다. 코드가 어느 곳에 위치하는지 예상할 수 있도록 디렉터리 구조를 구성하면 코드를 파악하는데 도움이 된다.

 

실무에선 크게 두가지로 디렉터리 구조로 많이 나타냈던 것 같다.

첫 번째 디렉터리 구조는 코드가 하는 역할에 따라 디렉터리를 분리했고 두 번째 디렉터리 구조는 페이지(도메인 영역)에 따라 디렉터리를 분리했다. 애플리케이션이 커지고 복잡해지면 첫 번째 디렉터리 구조의 경우, 코드가 정의된 곳과 코드 사용되는 곳이 멀어지는 문제점이 발생한다.

두 번째 디렉터리 구조는 Featured Based라고 할 수 있는데 이렇게 구조를 가져간다면 문제를 해결할 수 있다. 애플리케이션 전반에서 공통으로 사용되는 것들만 Top Level의 @shared 디렉터리에서 관리하고 나머지는 응집도 높게 각각의 디렉터리에서 관리하는 것이다.

이런 디렉터리 구조에 대한 고민이 있던 와중에 안희종님의 글 - 지역성의 원칙을 고려한 패키지 구조: 기능별로 나누기을 읽었는데, 참고하면 좋을 것 같다.

 

확장성 있는 코드

확장이 어려운 코드는 내부에서 많은 변경이 발생하며 이것은 코드를 읽기 어렵게 만든다. 자연스럽게 생산성도 떨어진다.

확장에 닫혀있다는 뜻은 객체에 새로운 값을 전달하기 어려운 구조라는 뜻이다. 객체의 유형에 따라 새로운 코드를 반복해서 작성하고, 동일한 로직을 수행하는 비효율적인 코드를 낭비하게 된다.

 

점진적으로 개선이 가능한 코드

앞서 여러 가지를 이야기 했지만 결국, 처음부터 완벽한 코드를 작성하는 것이 어렵다는 것을 인정하고 끊임없이 개선할 수 있는 코드를 작성하는 것이 중요하다. 결국 개선을 빠르게 할 수 있는 코드도 중요하지만 개선으로 인해 발생하는 문제를 조기에 감지할 수 있는 시스템이 필요하게 된다. 매번 수동으로 확인할 수 없으니 자연스럽게 ‘자동화 된 테스트’를 찾게 된다.

 

테스트

결국 테스트로 귀결된다. 앞서 이야기 한 좋은 코드들의 특징은 사실 테스트 코드를 작성하기에 용이한 코드들이다. 인터페이스를 통한 참조, 구현의 분리, 하나의 기능에 집중하는 모듈화 등 테스트 코드를 작성하다보면 개선하게 되는 지점들이다. 테스트를 작성하다 보면 코드를 작성하면서 놓친 부분들이 보인다. 새로운 관점이 생기게 되는데 역설적으로 이러한 지점들이 좋은 코드를 만들어내곤 한다.

 

결론

 

So What?

좋은 코드를 왜 작성해야 하는지부터 고민했던 과정을 글로 정리해보았다.

• 코드 간의 의존성을 고민하자.
• 합의된 규칙으로 일관성있게 작성하자.
• 적절하게 확장 가능하도록 설계하자.
• 어쩔 수 없는 코드는 주석과 함께 격리하자.
• 답은 테스트 코드 기반의 자동화 테스트다.

모든 코드를 테스트해야 하는가?라고 묻는다면 답은 없다. 파레토 법칙에 의하면 80%의 버그는 20% 코드에서 나온다. 20% 코드 지점을 찾아 이 부분만 테스트 코드를 작성하든, 새롭게 작성되는 영역에만 테스트 코드를 작성하든 선택이다.