사람이 읽는 코드(Human Readable Code)란? 유창한 API와 도메인 언어로 협업하기

핵심 메시지

• 코드를 '컴퓨터가 동작하도록'이 아니라 '사람이 읽도록' 만드는 데 초점을 두면 협업의 질이 달라진다.
• 주석을 많이 다는 방식은 코드와 금세 어긋나, 사람용 설명과 컴퓨터용 코드가 따로 노는 문제를 낳는다.
• 프로그래밍 단어 대신 합의된 도메인 어휘로 코드를 짜면, 비개발자도 코드를 보고 옳고 그름을 검증할 수 있다.
• 이 방식의 진가는 특히 '검증 가능한 테스트'에서 드러나며, 자주 다루는 핵심 영역일수록 초기 투자 가치가 크다.

쉽게 이해하기

발표자는 소프트웨어 엔지니어와 의뢰인이 서로의 전문 영역을 완전히 알지 못한다는 점에서 출발한다. 전통적으로는 큰 명세 문서를 넘기고 개발자가 해석해 코드로 옮기지만, 제대로 이해했는지는 애플리케이션을 돌려봐야 알 수 있고 그때는 이미 몇 달이 지나 있다. 그래서 함께 코드를 보며 '이게 맞다/틀리다'를 바로 이야기할 수 있으면 좋겠다는 문제의식을 제시한다.

주석을 많이 다는 해법은 한계가 분명하다. 주석은 코드와 빠르게 어긋나고, 결국 사람용 설명과 컴퓨터용 코드라는 두 가지가 따로 존재하게 된다. '틀린 줄 알면서도 모두가 무시하는 포스트잇'에 비유한다. 또 특정 문제에 꼭 맞는 도메인 특화 언어(DSL)를 새로 만드는 방법도 있지만, 언어를 만드는 일 자체가 만만치 않다.

그래서 발표자는 자바 같은 주류 언어를 쓰되 가독성을 최우선으로 두는 방법을 택한다. 카드 덱 예시에서 '스페이드이면서 5 미만인 카드를 모두 찾아 출력하라' 같은 영어 문장에 최대한 가깝게 코드를 먼저 적는다. 동작 여부는 잠시 미루고, 먼저 '읽히는 모양'을 잡은 뒤 언어를 그 모양에 맞춰 가는 식이다.

이 과정에서 spades는 choice(선택지), print them은 action(동작), 결과는 selection(선택 묶음)처럼 합의된 용어로 개념을 하나씩 정의해 나간다. 점(.)으로 이어지는 한 줄짜리 '유창한(fluent) API'를 만들기 위해 메서드들이 적절한 타입을 반환하도록 다듬는다. and를 then으로 바꾸자는 제안처럼, 표현을 함께 고치며 공통 어휘를 발견하는 것 자체가 값진 통찰이 된다.

발표자는 비용과 한계도 솔직히 인정한다. 이런 작은 언어를 만드는 데는 한두 시간의 선행 투자가 들고, 일회성 작업이라면 굳이 그렇게까지 할 필요가 없다. 다만 자주 다루는 핵심 영역이라면, 새 기능을 빠르게 표현할 수 있어 투자 가치가 있다고 본다. 만든 작은 언어는 자바에 묶여 포터블하지 않지만, 같은 철학은 파이썬·자바스크립트·C#에서도 적용할 수 있다고 덧붙인다.

주요 인사이트

• 코드를 밑에서부터 쌓아 올리기보다, '이렇게 읽혔으면 좋겠다'는 최종 모습에서 출발해 언어를 그 모양에 맞춰 가는 접근이 핵심이다.
• 용어를 함께 합의하는 과정에서 개념의 진짜 의미가 드러난다. 발표자는 이 '공유 어휘의 발견'을 코드보다 더 값진 산출물로 본다.
• 이 방식이 가장 빛나는 곳은 테스트다. 의뢰인이 직접 읽고 '이 테스트가 맞다'고 검증한 뒤 통과한다면, 시스템이 올바르다는 확신이 훨씬 커진다.
• '사람을 위한 코드'는 비개발자가 코드를 작성하지는 못해도 최소한 검증은 할 수 있게 하여, 오해로 인한 값비싼 재작업을 줄여 준다.

자주 묻는 질문