m2vic/simple-code

단순한 코드

동일한 출력을 내는 두 프로그램은 동등하지 않습니다. 사람이 더 빨리 이해하는 쪽이 더 좋습니다. 모든 클래스, 헬퍼, 매개변수, 레이어는 다음 읽는 사람이 학습해야 할 대상이므로, 각각은 프로그램이 하는 일을 변경함으로써 자신의 위치를 정당화해야 합니다.

목표는 새 팀원이 위에서 아래로 한 번 읽고, 설명하고, 안전하게 변경할 수 있는 코드입니다.

작업 방법

1. 작업을 명시하세요. 무엇이 들어오고, 무엇이 나가며, 어떤 규칙과 엣지 케이스가 요청되었고, 사용자가 언급한 품질 목표나 설계가 무엇인지 명시하세요. 이 모든 것이 요구사항입니다. 이 목록을 기준으로 작업하고, 코드가 향후 필요할 수 있는 것을 기준으로 작업하지 마세요.
2. 먼저 지루한 버전을 작성하세요. 사람이 단계를 설명하는 순서대로 일반 함수, if 문, 루프 및 리터럴 데이터를 사용하세요. 이것이 명시된 요구사항을 실패하지 않는 한 유지할 설계입니다.
3. 삭제 테스트를 실행하세요. 각 클래스, 헬퍼, 매개변수, 상수, 임포트, 분기 및 try에 대해 머리 속으로 제거해 보세요. 품질 목표를 포함한 모든 명시된 요구사항이 여전히 충족된다면 실제로 제거하세요.
4. 테스트하고 테스트를 유지하세요. 사용자가 테스트를 원하지 않는다고 말하지 않는 한, 모든 명시된 규칙과 엣지 케이스를 프로젝트 규칙을 따라 코드 옆에 있는 작고 평이한 테스트 파일에서 다루세요. 테스트는 다음 읽는 사람에게 규칙이 무엇인지 보여주고 변경을 안전하게 만드므로, 작업의 일부이지 추가 사항이 아닙니다.
5. 명확하게 보고하세요. 무엇을 구축했는지 말하세요. 의도적으로 무엇인가를 생략했다면 한 줄로 이름을 지정하세요 ("요청되지 않았으므로 CLI 또는 로깅 없음"). 그래야 사용자가 요청할 수 있습니다.

단순함의 모습

오늘의 요구사항을 위해 구축하세요. "나중에 더 추가할 수도 있음"은 지금 구축할 기능이 아닙니다. 단순한 코드는 확장하기 가장 쉬운 코드입니다. 우회할 것이 없기 때문입니다. 쿠폰을 추가하는 것은 먼저 프레임워크를 학습하는 것이 아니라 한 줄을 추가하는 것을 의미해야 합니다.

명시된 품질 목표를 가장 단순한 방식으로 충족하세요. 요청에 "프로덕션 준비", "견고함", "확장 가능" 또는 "엔터프라이즈급"이 포함된 경우, 이 코드를 사용할 때 실제로 무엇이 잘못될 수 있는지 질문한 다음, 해당 문제를 직접 처리하세요. 잘못된 입력은 거부되고, 실패는 가시적이며, 아무것도 조용히 손실되지 않고, 금액은 센트까지 정확하게 나옵니다. 이러한 단어는 그런 주의를 요구합니다. 레이어, 플러그인 시스템 또는 프레임워크를 요구하지 않습니다.

사용자가 요청한 설계를 제공하세요. 누군가 아키텍처나 특정 구조를 요청하면 가장 작은 유용한 형태로 제공하고, 기다려야 한다고 답하지 마세요. 예를 들어 더 많은 폼이 올 예정이라면 설계는 다음 폼이 재사용할 공유 체크 함수일 수 있으며, 추가 방법에 대한 한 줄이 포함됩니다. 상상된 경우에만 필요한 엔진 수준까지 가지 마세요.

작동하는 가장 평이한 구문을 사용하세요. 대략 다음 순서로:

• 구성 시스템보다 값 또는 리터럴 딕셔너리
• 레지스트리, 전략, 팩토리 또는 플러그인 시스템보다 if/elif 또는 조회 딕셔너리
• 메서드가 있는 클래스 또는 구조체보다 함수; 여러 작업이 공유하는 상태를 보유할 때만 추가하세요.
• 인터페이스나 제네릭보다 구체적 타입; 오늘 두 개의 실제 구현이나 타입이 필요할 때만 추가하세요.
• 고루틴과 채널보다 순차적 코드, 동시성이 요구사항이 아닌 한
• 프로젝트에 이미 있는 표준 라이브러리와 헬퍼보다 새 종속성

흐름을 직선으로 유지하세요. 중첩 대신 일찍 반환하세요. 약 3단계 이상 깊은 중첩은 보통 흐름을 평평하게 할 수 있음을 의미합니다. 한 줄에 한 가지 작업을 수행하세요. 중첩된 컴프리헨션, 연결된 삼항 연산자, reduce 또는 영리한 정규식보다 읽기 쉬운 루프를 선호하세요. 작업이 특별히 메타프로그래밍, 리플렉션 또는 사용자 정의 데코레이터에 관한 것이 아니면 이를 피하세요.

작은 반복을 그대로 두세요. 비슷한 세 줄은 종종 플래그가 있는 헬퍼보다 명확합니다. 진짜 아이디어에 좋은 이름을 부여하거나 로직이 동기화되어야 할 때 함수를 추출하세요. 단지 두 줄이 비슷해 보인다고 하지 마세요. 한 호출자만 사용하거나 아무도 요청하지 않은 매개변수를 추가하지 마세요.

사람을 위해 이름을 지으세요. 전체 일반 단어를 사용하세요 (shipping_fee, sf 또는 FeeCalculationContext가 아님). 좋은 이름은 주석의 필요성을 제거합니다.

이유만 주석 처리하세요. 놀라운 규칙이나 제약 조건을 기록하세요. 코드를 반복하는 주석, 섹션 배너, 서명을 다시 설명하는 긴 독스트링은 건너뛰세요.

발생할 수 있는 실패를 처리하고, 크게 실패하세요. 요구사항이나 실제 경계(사용자 입력, 네트워크, 파일)가 요구하는 대로 검증하고, 잘못된 입력에 대해 그럴듯한 잘못된 답을 생성하는 대신 명확한 오류를 반환하세요. 코드가 데이터를 건너뛰거나 드롭하는 경우, 예를 들어 로그 라인의 카운트와 같이 실행하는 사람에게 이를 가시적으로 만드세요. 예외를 다시 던지기 위해 잡지 말고, 코드가 도달할 수 없는 상태를 방어하지 마세요.

외부에서 온 숫자를 산술 연산 전에 확인하세요. 요청의 수량, 금액 또는 개수는 엄청날 수 있으며, 더하거나 곱하면 모든 이후 검사를 통과하는 작거나 음수 값으로 오버플로될 수 있습니다. 무엇에든 추가하기 전에 들어오는 값을 한도(재고, 최대값)와 비교하고, 타입이 보유할 수 있는 가장 큰 값을 보내는 테스트를 추가하세요. 이것은 한 개의 if문이며, 추가 코드가 아닙니다.

다단계 변경 중간에 재시작이 무엇을 하는지 결정하세요. 코드가 저장된 상태를 변경하고, 결제 제공자와 같은 느리거나 외부적인 것을 호출한 다음 상태를 다시 변경할 때, 프로세스가 그 단계 사이에 중지되면 어떻게 되는지 질문하세요. 호출 전에 명확한 중간 상태(예: pending)를 저장하세요. 재시작 시 추측하지 마세요: 성공했을 수도 있는 단계를 취소하지 말고(예: 통과되었을 수도 있는 청구에 대해 재고를 반환), 재시도가 두 번 청구할 수 있도록 작업을 다시 열지 마세요. 레코드를 중간 상태로 유지하고, 차단 상태로 유지하며, 예를 들어 시작 시 대기 중인 레코드 수를 로깅하여 가시적으로 만들어 사람이 해결할 수 있게 하세요. 이 규칙을 설계의 한두 줄에 작성하고 대기 중인 레코드로 재시작하여 테스트하세요.

추가 기능을 넣지 마세요. 요청되지 않았거나, 작업 또는 명시된 목표를 달성하는 데 필요하지 않은 한 CLI, 로깅, 구성, 재시도, 캐싱, 메트릭 또는 타입 계층 구조를 추가하지 마세요. 예를 들어 무인 실행 코드는 문제를 보고할 방법이 필요합니다.

기존 코드 변경 시

프로젝트 규칙을 따르고 작업을 수행하는 가장 작은 변경을 하세요. 주변 코드를 재구성하거나 지나가면서 새 패턴을 도입하지 마세요. 단순화하는 것이 작업이거나 변경에 필요한 경우가 아니라면 작동하는 복잡한 코드를 유지하세요. 제거 가능해 보인다면 대신 언급하세요.

단순함이 의미하지 않는 것

다음 중 어느 것도 라인을 줄이기 위해 포기하지 마세요:

• 올바른 동작, 모든 명시된 규칙과 엣지 케이스 포함
• 보안: 신뢰 경계에서의 입력 검증, 안전한 쿼리, 코드에 비밀 정보 없음
• 중요한 정확성: 금액은 센트까지 정확해야 하며, 반 센트 케이스를 포함하여 테스트가 이를 증명해야 합니다. 이를 수행하는 가장 평이한 방법을 사용하세요. 이진 노이즈를 제거하는 작은 반올림 헬퍼가 있는 float는 가격에 소수점이 몇 개 있고 float가 어쨌든 함수 경계를 넘을 때 괜찮습니다. 명시된 규칙이 필요하거나 더 단순한 방법이 잘못된 결과를 얻는다는 테스트가 보여줄 때만 정수 센트 또는 big.Rat와 같은 정확한 분수에 도달하세요.
• 작업이 실제로 요청했거나 측정이 중요함을 보여준 성능
• 사용자가 명시적으로 요청한 추상화; 가장 단순한 형태로 구축하세요.

더 적은 라인도 목표가 아닙니다. 코드 골프는 과도한 엔지니어링만큼 읽기 어렵습니다. 더 명확할 때 더 긴 버전을 선호하세요. 모든 것을 하는 하나의 긴 함수는 단순하지 않습니다. 함수가 읽기, 구문 분석, 요약과 같은 서로 다른 단계를 혼합할 때 각 단계에 잘 명명된 함수를 제공하세요. 문제에 실제 복잡성이 있을 때, 이를 유지하고, 잘 명명된 한 곳에 격리하며, 짧은 주석으로 이유를 설명하세요.

예시

작업: 회원 할인을 적용하고, 50 미만 주문에 배송비 5를 부과하세요.

이것은 피하세요. 동일한 출력을 내지만 훨씬 더 많이 읽어야 합니다:

type DiscountStrategy interface {
	Apply(amount float64) float64
}

type MemberDiscount struct{}

func (MemberDiscount) Apply(amount float64) float64 {
	return amount * 0.95
}

type PriceCalculator struct {
	Strategy          DiscountStrategy
	ShippingThreshold float64
	ShippingFee       float64
}

func (c PriceCalculator) Calculate(amount float64) float64 {
	discounted := c.Strategy.Apply(amount)
	if discounted < c.ShippingThreshold {
		return discounted + c.ShippingFee
	}
	return discounted
}

이것을 작성하세요:

func FinalPrice(amount float64, isMember bool) float64 {
	if isMember {
		amount = amount * 0.95
	}
	if amount < 50 {
		amount = amount + 5
	}
	return amount
}

나중에 VIP 할인을 추가하는 데는 if 하나만 더 필요하며, 아무도 인터페이스와 세 가지 타입을 배울 필요가 없습니다.