💡 Key Takeaways
- 1. Names Should Reveal Intent, Not Require Archaeology
- 2. Functions Should Do One Thing and Do It Well
- 3. Comments Should Explain Why, Not What
- 4. Keep Your Code DRY, But Not Bone Dry
마커스 찬, 포춘 500 기업 및 스타트업에서 14년간 확장 가능한 시스템을 구축한 수석 소프트웨어 엔지니어
💡 주요 포인트
- 1. 이름은 의도를 드러내야 하며 고고학이 필요하지 않아야 한다
- 2. 함수는 한 가지 일을 잘해야 한다
- 3. 주석은 무엇을 하는지가 아니라 왜 하는지를 설명해야 한다
- 4. 코드는 DRY하게 유지하되 뼈가 마르지 않도록 하라
세 년 전, 저는 제 경력 선택을 의심하게 만든 코드베이스를 물려받았습니다. 이전 팀은 기능을 매우 빠르게 제공했지만—정말 빠르게. 그러나 주 서비스 파일을 열어보니 엉킨 논리로 이루어진 4,200줄의 코드와 temp2와 finalFinal라는 이름의 변수, 17가지 다른 작업을 수행하는 함수들이 있었습니다. 단순한 버그 수정이 한 시간이 아닌 삼일이나 걸렸습니다. 그 프로젝트는 저에게 중요한 교훈을 주었습니다: 규율 없는 속도는 29% APR의 신용카드 이자처럼 증가하는 기술적 부채를 만듭니다.
그 이후로 저는 클린 코드를 저의 집착으로 삼았습니다. 5천만 사용자를 위한 레거시 시스템을 리팩토링하고, 80명 이상의 개발자를 멘토링하며, 이 원칙을 채택하여 팀들이 생산성을 변모하는 모습을 지켜보았습니다. 데이터는 설득력이 있습니다: 클린 코드 원칙을 실천하는 팀은 버그 밀도를 40-60% 줄이고, 신규 개발자에 대한 온보딩 시간을 절반으로 줄입니다. 더 중요한 것은, 장기적으로는 자신들의 코드베이스와 끊임없이 싸우지 않기 때문에 기능을 더 빠르게 배포합니다.
클린 코드는 규칙을 따르는 것이나 형식적인 것이 아닙니다. 그것은 존중에 관한 것입니다—미래의 자신, 동료, 그리고 당신의 작업을 유지보수할 다음 개발자에 대한 존중입니다, 그들이 오전 2시에 프로덕션이 중단되었을 때 말입니다. 제가 코드를 작성하는 방식과 제가 이끌었던 팀들이 소프트웨어를 배포하는 방식을 변화시킨 10가지 원칙입니다.
1. 이름은 의도를 드러내야 하며 고고학이 필요하지 않아야 한다
제가 현재 회사에서 코드를 처음 검토했을 때, processData()라는 함수와 마주쳤습니다. 그것이 실제로 무엇을 하는지 이해하는 데 45분이 걸렸습니다: 사용자 입력을 검증하고, 통화 값을 변환하고, 세 개의 데이터베이스 테이블을 업데이트하고, 두 개의 서로 다른 이메일을 보내고, 분석 이벤트를 기록하는 것이었습니다. 이름은 이러한 복잡성에 대해 아무것도 드러내지 않았습니다.
좋은 이름 짓기는 클린 코드의 기초입니다. 우리는 코드를 쓰는 것보다 읽는 시간을 훨씬 많이 소비하기 때문입니다. 연구에 따르면 개발자는 코드를 읽고 이해하는 데 58%의 시간을 사용하고, 실제로 코드를 작성하거나 수정하는 데는 42%를 소비합니다. 모호한 이름은 그 읽기 시간을 세금처럼 씁니다, 이 코드를 만지는 모든 개발자에게 곱해져서 말입니다.
여기 저의 이름 짓기 프레임워크가 있습니다: 변수나 함수의 이름은 구현을 읽지 않고도 세 가지 질문에 대답해야 합니다. 무엇을 나타내는가? 무엇을 하는가? 왜 존재하는가? d라는 변수는 이 질문에 아무것도 대답하지 못합니다. daysSinceLastModification라는 변수는 세 가지 모두에 대답합니다.
함수의 경우, 저는 철저히 동사-명사 패턴을 따릅니다. getUserById()는 명확합니다. get()는 쓸모가 없습니다. handleUserData()는 애매합니다—어떤 방식으로 다루는가? 불리언 변수의 경우, 저는 술어를 사용합니다: isActive, hasPermission, canEdit. 이것들은 조건문에서 자연스럽게 읽힙니다: if (isActive && hasPermission)와 if (active && permission)를 비교해 보십시오.
저는 팀들이 수백 시간을 낭비하는 것을 보았습니다. 누구든지 코드베이스의 절반에서 customer를 cust로 축약하고, 다른 절반에서는 cstmr로 축약한 경우입니다. 일관성은 매우 중요합니다. 이름 규칙을 조기에 설정하고, 코드 리뷰와 린팅 규칙을 통해 집행하세요. 당신의 미래의 자신은 자정에 디버깅을 할 때 tmp_val_2가 무엇을 나타내는지 해독할 필요가 없기를 바라게 될 것입니다.
제가 사용하는 하나의 실용적인 기술은: 만약 즉시 좋은 이름이 떠오르지 않으면, 변수나 함수가 무엇을 하는지를 설명하는 주석을 작성한 다음, 그 주석을 이름으로 바꿉니다. 만약 이름이 너무 길어지면(4-5 단어를 초과하면) 보통 그 함수가 너무 많은 일을 하고 있어서 분리해야 한다는 신호입니다.
2. 함수는 한 가지 일을 잘해야 한다
단일 책임 원칙은 단순히 학문적 이론이 아닙니다—유지보수 가능한 코드와 유지보수의 악몽의 차이입니다. 이는 사용자 등록, 이메일 확인, 결제 처리, 분석 추적을 처리하는 300줄의 함수를 디버깅하면서 어려운 방법으로 배웠습니다. 버그를 찾는 데 6시간이 걸렸습니다. 수정하는 데는 5분이면 충분했습니다.
"코드를 읽는 데 소모되는 시간과 코드를 쓰는 데 소모되는 시간의 비율은 10대 1을 넘습니다. 우리는 새로운 코드를 작성하기 위해서 고전 코드를 지속적으로 읽고 있습니다. 읽기 쉽게 만드는 것은 쓰기 쉽게 만듭니다." — 로버트 C. 마틴
함수는 한 가지 일을 해야 하며, 그 일을 잘하고 오직 그 일만 해야 합니다. 하지만 "한 가지"라는 것은 무엇을 의미할까요? 제 추정 규칙: 함수가 "그리고"라는 단어를 사용하지 않고 기능을 설명할 수 없다면, 그것은 너무 많은 일을 하고 있습니다. validateUserInput()는 한 가지 일을 합니다. validateUserInputAndSaveToDatabase()는 두 가지 일을 하며 분리되어야 합니다.
저는 10-20줄 길이의 함수를 목표로 합니다. 일부 개발자는 이것이 극단적이라고 생각하지만, 작은 함수는 막대한 이점을 가지고 있습니다. 테스트하기가 더 쉽습니다—복잡한 시나리오를 설정하지 않고도 하나의 동작을验证할 수 있습니다. 재사용하기가 더 쉽습니다—작고 집중된 함수는 더 큰 작업을 위한 빌딩 블록이 됩니다. 이해하기가 더 쉽습니다—스크롤하지 않고도 전체 함수를 파악할 수 있습니다.
저는 큰 함수를 리팩토링할 때 코드가 추상화 수준이 변하는 자연스러운 이음새를 찾습니다. 입력을 검증하고, 데이터를 변환하고, 데이터베이스에 저장하는 함수는 세 가지 다른 수준에서 작동합니다. 저는 각 수준을 자신의 함수로 추출합니다: validateOrderData(), transformOrderForStorage(), saveOrder(). 원래 함수는 이 세 함수를 순차적으로 호출하는 조정자 역할을 하게 됩니다.
이 접근 방식은 오류 처리를 더 깔끔하게 만듭니다. 50줄에 걸쳐 있는 중첩된 try-catch 블록 대신 각 작은 함수가 자신의 오류를 적절히 처리합니다. 조정자 함수는 구현 세부사항에 얽히지 않고 높은 수준의 오류 시나리오를 처리할 수 있습니다.
저는 이 원칙이 제 팀에 미친 영향을 측정했습니다. 엄격한 함수 크기 제한을 채택한 후, 버그 수정 평균 시간이 4.2시간에서 1.8시간으로 감소했습니다. 신규 팀원은 개별 함수를 이해할 수 있었기 때문에 생산성이 40% 더 빨라졌습니다. 전체 시스템을 먼저 이해할 필요가 없었습니다.
3. 주석은 왜 하는지를 설명해야 하며, 무엇을 하는지에 대해서는 말할 필요가 없다
경력 초기에, 저는 좋은 코드가 많은 주석을 의미한다고 생각했습니다. // 카운터를 1 증가시킵니다와 같은 것을 counter++ 위에 작성했습니다. 제 시니어 개발자가 제게 다가와서 제 시각을 바꾸는 말을 했습니다: "코드가 무엇을 하는지를 설명하기 위해 주석이 필요하다면, 당신의 코드는 충분히 명확하지 않은 것입니다."
| 측면 | 더러운 코드 | 클린 코드 | 영향 |
|---|---|---|---|
| 함수 이름 | processData(), doStuff(), handleIt() | validateAndTransformUserInput(), sendWelcomeEmail() | 이해하는 데 걸리는 시간 70% 감소 |
| 함수 길이 | 200-500+ 줄, 여러 책임 | 10-20 줄, 단일 책임 | 버그 밀도 40-60% 감소 |
| 변수 이름 | temp2, finalFinal, x, data | userEmailAddress, validatedOrderTotal | 온보딩 시간 절반 감소 |
| 주석 | 코드가 무엇을 하는지 설명 | 결정한 이유 설명 | 유지보수 시간 50% 감소 |
| 코드 중복 | 5개 이상의 파일에 동일한 논리 복사 | 재사용 가능한 함수로 추출됨 | 변경 시 1회 편집 대 5+회 편집 |
주석은 결정을 내린 이유를 설명해야 하며, 코드가 무엇을 하는지를 설명할 필요는 없습니다. 코드 자체는 좋은 명명법과 명확한 구조를 통해 자명해야 합니다. // 사용자를 반복합니다라는 주석을 for 루프 위에서 보려고 할 때, 그건 노이즈입니다. 루프 자체가 사용자를 반복하고 있음을 보여주기 때문입니다. 그러나 // 배열이 일반적으로 5-10 항목이므로 선형 검색을 사용합니다. 이진 검색의 오버헤드는 가치가 없습니다.와 같은 주석은 가치가 있습니다. 코드 자체에서는 분명하지 않은 결정을 설명합니다.
저는 주석을 통해 비자명한 비즈니스 규칙을 문서화하고, 타사 라이브러리 버그에 대한 우회 솔루션을 설명하거나, "명백한" 솔루션을 사용하지 않는 이유를 명확히 합니다. 예를 들어: // Safari 12가 서비스 워커에서 지원하지 않으므로 여기서는 async/await를 사용할 수 없습니다. 그리고 8%의 사용자가 여전히 Safari 12를 사용하고 있습니다.라는 주석은 다음 개발자가 "잘못된" 것을 "수정"하지 못하게 방지합니다.
경고 주석은 또 다른 정당한 사용 사례입니다. // 경고: 이 타임아웃을 변경하면 결제 프로세서의 속도 제한에 영향을 미칩니다. 수정하기 전에 티켓 #1234를 확인하세요. 이것은 잘못된 의도의 변경을 방지합니다.