Clean Code: 10 Rules I Actually Follow (And 5 I Ignore)

저는 현재 월 23억 달러의 거래를 처리하는 핀테크 회사의 수석 소프트웨어 아키텍트로서 14년 동안 다른 사람들의 코드를 지켜보았습니다. 지난 화요일, 제가 몸서리를 치게 만든 풀 리퀘스트를 리뷰했습니다 — 하나의 함수에 847줄, "data2"와 "temp" 같은 변수 이름, 그리고 "// magic happens here"라는 글이 달린 주석. 이를 작성한 개발자는? GPA 3.9를 가진 스탠포드 컴퓨터 과학 졸업생입니다.

그때 저에게 깨달음이 왔습니다: 우리는 클린 코드 교육을 잘못하고 있었습니다.

모두가 Uncle Bob의 "클린 코드"를 경전처럼 인용합니다. 그들은 SOLID 원칙을 암기하고, tab 대 space에 대해 논쟁하며, 현미경으로 읽어야 할 만큼 너무 작은 함수를 작성합니다. 그러나 아무도 말하지 않는 것이 있습니다: 그 규칙 중 일부는 실제로 코드의 품질을 저하시킵니다.

저는 로버트 마틴의 작업을 폄하하려는 것이 아닙니다 — 그것은 기초적이고 중요합니다. 그러나 3,000개가 넘는 풀 리퀘스트를 리뷰하고, 47명의 개발자를 멘토링하며, 2011년부터 운영되고 있는 코드베이스를 유지 관리하면서, 어떤 규칙이 실제로 중요한지와 어떤 규칙이 단지 개발자 연극에 불과한지 배웠습니다. 제가 무슨 뜻인지 보여드리겠습니다.

제가 따르는 규칙 #1: 함수는 한 가지 일을 해야 합니다 (하지만 그 일은 생각보다 더 클 수 있습니다)

함수에 대한 "단일 책임 원칙"은 클린 코드에서 가장 오해받는 규칙일 것입니다. 저는 개발자들이 "validateUserEmailFormat"과 같은 세 줄 길이의 함수를 만들고, 그것이 "validateUserEmail"로 호출되고, 다시 "validateUser"로 호출되는 걸 봅니다. 거북이가 내려가는 것처럼, 사용자가 가입할 때 무슨 일이 일어나는지를 이해하려면 일곱 개의 파일을 열어야 합니다.

제가 실제로 하는 일은 다음과 같습니다: 저는 하나의 의미 있는 비즈니스 작업을 수행하는 함수를 작성합니다, 하나의 기술적 작업이 아니라. "processPayment"라는 함수는 45줄이 될 수 있습니다. 결제 수단을 검증하고, 사기를 확인하고, 거래 기록을 만들고, 확인 이메일을 보냅니다. 그것은 네 가지 기술적 작업이지만, 하나의 비즈니스 작업입니다: 결제 처리.

핵심은 각 단계가 코드에서 명확하게 구분된다는 것입니다. 저는 논리적 섹션을 분리하기 위해 빈 줄을 사용하고, 각 섹션의 "왜"를 설명하는 간단한 주석을 추가합니다. 다른 개발자가 "processPayment"를 읽으면, 열두 개의 다른 파일 사이를 왔다 갔다 하지 않고도 전체 결제 흐름을 이해할 수 있습니다.

저는 한 번 이것을 측정해 보았습니다. 우리가 "함수는 작아야 한다"라는 규칙을 철저하게 따르던 구 코드베이스에서, 평균 개발자는 단일 사용자 흐름을 이해하기 위해 8.3개의 파일을 열어야 했습니다. "의미 있는 작업" 함수를 사용하도록 리팩토링 후, 그 수치는 2.1개로 줄어들었습니다. 코드 리뷰 시간은 34% 감소했고, 버그 수정 시간은 28% 줄어들었습니다.

규칙은 "함수를 작게 만드는 것"이 아닙니다. 규칙은 "함수를 이해할 수 있도록 만드는 것"입니다. 때로는 10줄이 될 수 있고, 때로는 50줄이 될 수 있습니다. 절대로 개발자들이 버튼 클릭이 어떻게 작동하는지를 이해하기 위해 전체 코드베이스를 탐색하도록 강요하는 것은 아닙니다.

제가 따르는 규칙 #2: 이름은 의도를 드러내야 합니다 (비록 길더라도)

저는 한 번, 변수 이름이 15자를 초과해서는 안 된다고 주장하는 개발자와 함께 일했습니다. 왜냐하면 "코드를 읽기 어렵게 만든다"고 했습니다. 그는 다음과 같은 코드를 작성했습니다: "const usrPmtMthd = getUserPaymentMethod();" 저는 키보드를 창 밖으로 던지고 싶었습니다.

"가장 좋은 코드는 가장 교묘한 코드가 아닙니다 — 다음 개발자가 시스템이 다운되어 고객들이 전화를 걸 때 오전 2시에 이해할 수 있는 코드입니다."

제 규칙은 이렇습니다: 제가 변수 이름을 한 번 읽고 그 내용이 무엇인지 이해할 수 없다면, 그 이름은 잘못된 것입니다. 이름이 40자든 상관 없습니다. "pmtMthd"가 무엇을 의미하는지 알아내는 데 세 분이 걸리기보다는 "userSelectedPaymentMethodFromDropdown"을 읽는 것이 낫습니다.

우리의 결제 처리 시스템에는 "transactionRequiresAdditionalFraudVerificationBasedOnUserHistory"라는 변수가 있습니다. 이는 71자입니다. 또한 아주 명확합니다. if 문에서 그 변수를 보면, 무엇이 체크되고 있는지, 왜 체크되고 있는지 정확히 알 수 있습니다. 주석이 필요 없습니다. 정신적인 번역도 필요 없습니다.

항상 나는 "하지만 긴 이름은 줄을 너무 길게 한다!"는 반론을 듣습니다! 물론, 우리가 여전히 1985년의 80열 단말기에서 코드를 작성한다고 가정한다면요. 우리는 이제 27인치 모니터를 가지고 있습니다. 이를 활용하세요. 저는 제 줄 길이 제한을 120자로 설정하며, 가독성 문제를 경험한 적이 없습니다.

제가 사용하는 테스트는 이렇습니다: 만약 주니어 개발자가 변수 이름을 읽고 즉시 그 내용, 유형, 그리고 대략 어떤 용도로 사용되는지를 알 수 있다면, 그 이름은 올바르게 지어진 것입니다. 만약 그들이 어디에서 선언되었는지 확인하거나 유형 정의를 보기 위해 스크롤해야 한다면, 실패한 것입니다.

저는 이것이 코드 리뷰 품질을 극적으로 향상시키는 것을 보았습니다. 이름이 명확할 때, 리뷰어는 "이게 뭐지?"라고 묻는 데 시간을 덜 쓰고 "이게 올바른 접근법인가?"라고 묻는 데 더 많은 시간을 씁니다. 진정한 가치는 그곳에 있습니다.

제가 따르는 규칙 #3: 주석은 '왜'를 설명해야 합니다, '무엇'이 아니라 (하지만 생각보다 더 많이 사용하세요)

클린 코드 순수주의자들은 "좋은 코드는 주석이 필요하지 않다"고 말할 것입니다. 그들은 반은 맞습니다. 좋은 코드는 코드가 무엇을 하는지 설명하는 주석이 필요하지 않습니다. 하지만 코드가 존재하는 이유를 설명하는 주석은 절대적으로 필요합니다.

지난달, 저는 우리 코드베이스에서 이상한 해결책이 있는 함수를 찾았습니다: 웹훅을 처리하기 전에 50밀리초 지연을 추가하고 있었습니다. 주석도 설명도 없습니다. 단지 "await sleep(50);"이 지뢰처럼 앉아 있었습니다. 저는 그것이 버그인지 고의인지를 알아내기 위해 두 시간을 보냈습니다. 알고 보니 이는 서드파티 API에서 발견된 경쟁 조건의 임시 방편이었고, 생산 환경에서 3일 간 디버깅을 한 결과 발견된 것이었습니다.

이제 그 코드에는 주석이 달려 있습니다: "// 50ms 지연 필요: 스트라이프의 웹훅은 API가 충전 상태를 반영하기 전에 도착할 수 있습니다. 2023-08-15의 사건 #2847에서 발견됨. 스트라이프가 eventually consistency 문제를 수정하면 이 부분을 제거하세요 (티켓 #45892)."

좋은 주석입니다. 코드 존재의 이유를 설명하고, 그것을 초래한 사건을 언급하며, 나중에 이를 제거하는 방법을 제공합니다. 그 주석이 없다면, 다음 개발자는 실수로 그것을 삭제할 수 있습니다.

저는 세 가지 상황에서 주석을 자유롭게 추가합니다: 의존성의 버그를 우회하고 있을 때, 비자명한 비즈니스 규칙을 구현할 때, 코드 가독성을 떨어뜨리는 방식으로 성능을 최적화할 때입니다. 각 경우에서 주석은 코드 자체에서 볼 수 없는 맥락을 설명합니다.