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

저는 중간 규모의 핀테크 회사에서 수석 소프트웨어 아키텍트로 14년 동안 다른 사람들의 코드를 바라보고 있으며, 제가 깨끗한 코드 열렬한 신봉자를 그만두게 된 정확한 순간을 말씀드릴 수 있습니다: 2019년 3월 화요일 오전 2시 47분, 누군가가 완벽하게 작동하는 모듈을 아저씨 밥의 책에 있는 모든 규칙을 따르도록 리팩토링하는 데 3일을 보낼 때 우리의 결제 처리 시스템이 중단되었습니다. 아이러니하게도? 버그는 "정리"하는 동안 발생했습니다.

그날 밤은 코드 품질에 대한 제 생각을 바꿨습니다. 저는 깔끔한 코드 원칙이 잘못되었다고 말하는 것이 아닙니다—전혀 아닙니다. 하지만 10,000개 이상의 풀 리퀘스트를 검토하고 47명의 개발자를 멘토링하며 23개의 주요 제품 릴리스를 출시한 결과, 규칙 집합에 대한 교조적인 고수는 또 다른 형태의 기술 부채라는 것을 배웠습니다. 일부 깔끔한 코드 규칙은 절대적인 금입니다. 다른 규칙은? 잘해봤자 상황 의존적이며, 최악의 경우에는 적극적으로 해로울 수 있습니다.

제가 실제로 프로덕션 코드에서 하는 일과 더 중요한 이유는 다음과 같습니다.

내가 따르는 규칙 #1: 함수는 하나의 작업을 해야 한다 (하지만 나는 "하나의 작업"을 다르게 정의한다)

함수에 대한 단일 책임 원칙은 제가 규칙적으로 따르는 가장 가치 있는 규칙일 것입니다. 그러나 여기서 제가 교과서와 다른 점은 다음과 같습니다: 저는 "하나의 작업"을 코드 줄 수나 연산 수로 측정하지 않습니다. 저는 개념적 응집력으로 측정합니다.

지난 분기, 저는 8줄 길이의 기능을 검토했지만 SRP를 놀라울 정도로 위반했습니다. 그것은 사용자 입력을 검증하고, 검증 결과를 기록하며, 캐시를 업데이트했습니다. 8줄에 세 가지Distinct 책임이 들어 있었습니다. 제가 지난 달 작성한 45줄의 함수와 비교해 보세요. 그 함수는 복잡한 데이터베이스 트랜잭션을 조정합니다—그것은 "하나의 작업"을 수행합니다 (결제 트랜잭션을 완료하는 것), 하지만 그 하나의 작업은 함께 있어야 하는 여러 단계를 요구합니다.

저의 시험 기준은 이렇습니다: 이 함수가 하는 일을 "그리고"라는 단어를 사용하지 않고 한 문장으로 설명할 수 있는가? "이 함수는 입력을 검증하고 이메일을 전송한다"고 말해야 한다면, 두 가지 일을 하고 있습니다. 하지만 "이 함수는 환불 요청을 처리한다"고 말하면, 그 자연스러운 과정에 검증, 데이터베이스 업데이트 및 알림이 포함되므로—그것은 여전히 적절한 추상화 수준에서 한 가지 작업입니다.

현실에서 이것은 제 함수가 순수주의자들이 권장하는 10-15줄 대신 평균 25-30줄이라는 것을 의미합니다. 하지만 이 함수들에 대한 버그 비율은 우리가 이전에 가지고 있던 과도하게 추출된 코드보다 40% 낮습니다. 그 이유는 무엇일까요? 관련된 작업을 함께 유지하면 시스템을 이해하기 위한 인지 부하가 줄어들기 때문입니다. 모든 것이 작은 함수로 나뉘어져 있을 때, 비즈니스 논리를 이해하는 것보다 파일 간을 이동하는 데 훨씬 더 많은 시간을 소모합니다.

여기서의 진정한 승리는 테스트 가능성입니다. 하나의 개념적 작업을 수행하는 함수는 길이가 40줄이더라도 테스트하기가 쉽습니다. 의존성을 모의하고, 함수를 호출하고, 결과를 확인합니다. 끝. 5줄 함수로 모든 것을 추출하면 단위 테스트가 의미가 없어지기 때문에 통합 테스트를 하게 됩니다.

내가 따르는 규칙 #2: 의미 있는 이름은 절대적으로 중요하다

저는 이 문제에서는 결코 타협하지 않을 것입니다: 변수와 함수 이름은 여러분이 작성할 가장 중요한 문서입니다. 저는 이름이 좋지 않다는 이유로 풀 리퀘스트를 거절한 적이 있고, 앞으로도 그렇게 할 것입니다.

"어떤 규칙 집합에 대한 교조적 고수는 또 다른 형태의 기술 부채입니다. 최고의 코드는 가장 깨끗한 코드가 아닙니다—신뢰성 있게 배송되고 팀에서 유지보수할 수 있는 코드입니다."

두 달 전, 한 주니어 개발자가 `processData()`라는 함수로 코드를 제출했습니다. 저는 10분짜리 룸 비디오를 첨부하여 왜 그런지를 설명하며 그것을 반송했습니다. 그 함수는 결제 카드 번호를 룬 알고리즘에 대해 검증하고 있었습니다. 올바른 이름은 `validateCardNumberChecksum()`였습니다. 그렇습니다, 더 깁니다. 그렇습니다, 더 구체적입니다. 그것이 바로 요점입니다.

다음은 수천 번의 코드 리뷰를 통해 다듬어진 제 이름 지정 계층 구조입니다:

• 불리언 변수: 항상 is/has/can/should로 시작합니다. `active`가 아니라 `isActive`. `permission`이 아니라 `hasPermission`입니다.
• 함수: 동작에 대한 동사, 쿼리에 대한 명사. `calculateTotalPrice()`가 아니라 `totalPrice()`. `getUserById()`가 아니라 `user()`입니다.
• 클래스: 개념을 나타내는 명사, 동작이 아닙니다. `PaymentProcessor`가 아니라 `ProcessPayments`입니다.
• 상수: 실제 상수에 대한 SCREAMING_SNAKE_CASE, 변경될 수 있는 설정에 대한 camelCase.

그 영향은 측정할 수 있습니다. 18개월 전 우리 팀에서 엄격한 이름 지정 규칙을 시행한 후, 평균 PR 검토 시간은 3.2시간에서 1.8시간으로 줄어들었습니다. 그 이유는 무엇일까요? 리뷰어가 코드가 무엇을 하는지를 해독하는 데 시간을 덜 소비하고, 그것이 올바르게 수행되는지 평가하는 데 더 많은 시간을 소비하기 때문입니다.

저는 또한 정확히 세 가지 예외가 있는 "약어 금지" 규칙을 시행합니다: `id`, `url`, 및 `api`. 다른 모든 것은 풀어서 설명합니다. `usr`는 `user`가 됩니다. `btn`은 `button`이 됩니다. `calc`는 `calculate`가 됩니다. 누군가 오후 11시에 디버깅을 하고 있을 때, `tmpBfr`이 의미하는 것을 추측할 필요가 없기 때문에 추가적인 입력은 가치가 있습니다.

내가 따르는 규칙 #3: 주석은 무엇이 아닌 왜를 설명한다

저는 제 경력에서 두 가지 극단을 보았습니다: 주석이 전혀 없는 코드베이스와 모든 줄에 주석이 있는 코드베이스. 둘 다 잘못되었습니다. 그러나 과도하게 주석이 달린 코드는 오히려 더 나쁩니다. 왜냐하면 유지보수 부담을 만들어내고 종종 거짓말을 하기도 때문입니다.

제 규칙은 간단합니다: 코드가 무엇을 하고 있는지를 설명하고 있다면, 그 코드는 아마 나쁩니다. 특정 결정을 내린 이유를 설명하고 있다면, 그것은 좋은 주석입니다. 여기서 진짜 예를 들어보겠습니다.