어려운 코드를 잘 설명하는 법

코드는 간결하고 이해하기 쉽게 작성해야 한다. 복잡한 코드는 유지보수와 협업에 어려움을 주며, 이는 기본 원칙이다. 여러 번의 코드 리뷰 후, 간결한 코드를 작성하려는 노력을 더욱 강화하게 되었다. 하지만 쉬운 코드를 작성하는 것은 항상 어려운 일이다.

최근, 나는 복잡한 코드를 작성한 경험이 있다. 팀장님과 함께 검토하여 개선할 수 있었고, 이 과정에서 커뮤니케이션에 대한 통찰을 얻었다. 이에 개발자가 복잡한 코드를 설명할 때 효과적인 접근법을 공유하고자 한다.

개발자 미션: 팀원들을 이해시키기

1. 무엇보다 쉽게 짜야 한다(가장 중요한 원칙!)

"읽기 좋은 코드가 좋은 코드다." 코드는 프로그램 실행뿐 아니라 소통의 도구이다. 복잡한 코드는 이해하는 데 더 많은 시간이 걸리며, 간결하고 명료한 코드는 오류를 발견하기 쉽게 한다. 복잡한 코드를 접했을 때는 그 원인을 분석해야 한다.

• 여러 기능이 한 곳에 몰려 있음
• 나쁜 추상화로 책임이 불분명함

코드가 복잡하면 구조적 문제가 있을 가능성이 크다. 예를 들어, 최근 개발한 ‘럭키박스’ 기능에서는 확률형 상품과 보장형 상품이 섞여 있었다. 최하위 상품을 수집하기 위해 재귀 함수를 사용했으나, 보장형 상품에 다시 럭키박스가 포함되는 구조적 문제에 봉착했다.

이 경우, 모든 조합을 계산하기 위해 조합(combination) 알고리즘을 사용하여 코드를 간결하게 만들었다.

IEnumerable> CartesianCombine(List> sources){    IEnumerable> seed = new[] { new List() };    foreach (var source in sources)    {        seed = seed.SelectMany(prefix => source, (prefix, item) =>        {            var next = new List(prefix) { item };            return next;        });    }    return seed;}

2. 복잡한 코드를 설명해야 할 때

짧은 일정이나 기획 변경으로 복잡한 코드를 작성할 수밖에 없을 때, 간소화할 수 있는 방법을 고민해야 한다. 리뷰 과정에서 이러한 노력이 드러나면 팀원들이 이해하는 데 도움이 된다.

• 시간이 촉박할 때는 테스트 코드로 주요 로직을 보장하고, 리팩토링할 부분을 주석으로 남긴다.
• 아이디어가 없을 때는 기능 구현에 집중하고, 코드의 한계를 주석으로 기록하는 것이 좋다.

3. 이해하기 쉽게 설명하는 방법

리뷰어가 PR을 쉽게 이해할 수 있도록 설명을 작성하자. 다음 요소를 포함하는 것이 좋다.

• 어떤 기능을 구현했는지
• 조언이나 피드백이 필요한 부분
• 현재 코드의 한계 및 개선 방안

또한, 리팩토링 계획, 플로우차트 활용, 데이터 타입 시각화, 주석과 문서화 등의 방법도 유용하다.

좋은 코드는 이해할 수 있는 코드다

복잡한 코드를 단순화하거나 명확하게 설명하는 것이 중요하다. 체계적인 정리가 이루어지면 유지보수 과정에서 시간과 에너지를 절약할 수 있다. 복잡한 코드는 구조적인 문제의 신호일 수 있으니 원인을 분석하고 필요 시 기획 단계부터 재검토하는 용기가 필요하다.