변경 위생과 코드 장인정신은(는) 무엇을 하나요?
개요
변경을 구성하는 방법과 코드를 작성하는 방법. 두 가지 주제: 구조적 변경과 행동적 변경을 분리하고, 가장 덜 복잡하면서도 의도를 명확히 표현하라.
변경 위생 (Change Hygiene)
- 구조적 변경을 행동적 변경보다 먼저, 독립적으로 검증하라. 재구성(파일 분할, 이름 변경, 주석 추가)은 행동 변경(새로운 제약 조건, 로직 수정)과 별개의 독립적으로 확인 가능한 단계입니다. 둘을 하나의 분할할 수 없는 변경에 절대 섞지 마십시오. 리뷰어는 안전한 재구성과 실제 로직 변경을 구분할 수 없습니다.
- 변경 하나당 하나의 관심사. 변경은 단일하고 명시할 수 있는 목적을 가져야 합니다.
- 작업 중인 코드를 개선하되, 작업에 영향을 미치는 문제가 있을 때만 개선하십시오(야영장을 더 깨끗하게 떠나라). 그러나 관련 없는 리팩토링을 시작하지 마십시오. 목표에 집중하십시오.
코드 장인정신 (Code Craft)
- 암시적보다 명시적. 이름이 필요한 곳에 와일드카드를 사용하지 말고, 암시적 형변환을 하지 말며, 빈 문자열이나 매직 센티널을 사용하지 마십시오. 의도를 명확히 말하십시오.
- 설명적인 이름. 함수/변수는 그 기능을 설명해야 하며, 언어 및 생태계 관용구를 따라야 합니다.
- 의도를 주석으로 남기고, 메커니즘은 설명하지 마십시오. 명확하지 않은 경우 이유를 설명하고, 자명한 코드에는 주석을 생략하십시오.
- 작고, 단일 목적을 가진 단위. 모든 단위에 대해 내부를 읽지 않고도 그것이 무엇을 하는지, 어떻게 사용하는지, 무엇에 의존하는지 말할 수 있어야 합니다. 큰 파일은 보통 너무 많은 일을 하고 있습니다.
- 생산 코드에서는 판단력을 가지고 DRY 원칙을 적용하십시오. 중복은 신호이지 자동 오류가 아닙니다. 두 번째 거의 동일한 발생은 의도적인 결정(추상화할지, 또는 추상화하지 않는 이유를 기록할지)을 촉발합니다. 공유된 의미를 추상화하고, 우연한 형태(같아 보이지만 다른 이유로 변경되는 것들)는 분리하십시오.
- 생태계 표준을 따르십시오. 유능한 실무자가 기대하는 관용구와 잘 지원되는 라이브러리를 사용하십시오. 플랫폼이 이미 해결한 것을 다시 발명하지 마십시오.
명명된 긴장 관계
- DRY vs. 조기 추상화: 생산 코드는 의도의 반복이 입증된 경우에 추상화하고, 형태의 반복이 예상된다고 추상화하지 않습니다. 확실하지 않으면 세 번째 발생을 기다리십시오(YAGNI가 결정을 내립니다).
- DRY vs. DAMP: 생산 코드는 DRY여야 하고, 테스트 코드는 DAMP(중복 제거보다 명확성,
tests-as-a-control참조)여야 합니다. 테스트에 DRY를 적용하는 것은 위반입니다.
일반적인 합리화
| 변명 | 현실 |
|---|---|
| "파일 이름을 바꾸고 기능을 하나의 커밋에 추가하겠습니다" | 구조와 행동을 하나의 diff로 섞으면 리뷰할 수 없습니다. 분리하십시오. |
| "두 개의 복사본이 있으니 지금 당장 DRY해야 합니다" | 두 번째 발생 = 결정해야 함. 같은 형태 ≠ 같은 의미. 우연한 중복은 분리되어 있어야 합니다. |
| "여기 있는 김에 다른 모듈도 리팩토링하겠습니다" | 관련 없는 리팩토링은 범위와 위험을 확장합니다. 기록해 두고 지금은 하지 마십시오. |
| "교묘한 한 줄 코드가 더 우아합니다" | 명시적인 것이 교묘한 것보다 낫습니다. 다음 독자를 위해 최적화하십시오. |
위험 신호 — 중단
- 코드를 이동하면서 동시에 행동을 변경하는 diff
- 목적을 설명하는 데 "그리고"라는 단어가 필요한 PR
- 첫 번째 유사성에서, 또는 예상(실제가 아닌)되는 반복에서 추상화하는 경우
- 더 이상 머리 속에 담을 수 없는 파일
전체 근거: 헌법 제5조 및 제6조, engineering-constitution/references/engineering-constitution.md에 묶여 있습니다.