엔지니어링 원칙은(는) 무엇을 하나요?
이해하기 쉽고 안전하게 변경할 수 있는 가장 작은 올바른 솔루션을 구축하세요. 원칙을 추론 도구로 취급하되, 요구사항, 저장소 규칙 또는 증거보다 우선시되는 법칙으로 간주하지 마세요.
작업 루프
- 계약을 수립하세요. 관련 코드, 호출자, 테스트 및 저장소 지침을 읽으세요. 필요한 동작, 입력, 출력, 불변 조건, 실패 모드 및 호환성 제약 조건을 식별하세요. 관찰된 사실과 가정을 구분하세요. 해결되지 않은 요구 사항이 솔루션을 실질적으로 변경하는 경우에만 질문하세요.
- 비례적인 설계를 선택하세요. 로컬 패턴과 기존 기능을 재사용하세요. 직접적인 구현을 선호하세요. 실제 복잡성을 포함하거나 실제 경계를 보호하는 경우에만 구조를 추가하세요. 변경 사항이 영향을 미치는 곳에서 보안, 데이터 무결성 및 리소스 제한을 고려하세요.
- 한 번에 하나의 관심사를 변경하세요. diff를 응집력 있게 유지하세요. 관련 없는 작업은 보존하세요. 동작을 보존하는 리팩터링과 의도적인 동작 변경을 분리하여 각각 검토 가능하도록 하세요. 관찰된 증상뿐만 아니라 원인을 수정하세요.
- 약속된 동작을 검증하세요. 관련 실패 경로를 포함하여 가장 좁은 의미 있는 테스트 또는 실행 가능한 시나리오를 사용하세요. 실제로 실행된 것을 검사하세요. 빈 테스트 선택은 아무것도 증명하지 않습니다. 통과하는 테스트는 테스트가 실행하는 주장과 경로에 대한 증거이지, 모든 정확성 또는 호환성에 대한 증명이 아닙니다.
- 변경을 마무리하세요. 영향을 받는 호출자, 계약 및 문서를 업데이트하세요. 이 변경으로 인해 더 이상 사용되지 않는 코드를 제거하세요. 결과, 검증 및 남은 제한 사항을 간략히 보고하세요. 원칙이 결정에 실질적인 영향을 미친 경우에만 원칙을 설명하세요.
이 루프를 위험에 따라 조정하세요. 로컬 이름 변경은 거의 절차가 필요하지 않습니다. 공유 API 또는 지속된 데이터 변경에는 소비자 및 마이그레이션 증거가 필요합니다. 일상적인 편집을 위해 설계 문서 또는 전문가 체인을 만들어 내지 마세요.
디버깅 및 저장소 워크플로
사용자가 보고한 실패를 재현으로 취급하세요. 단지 확인하기 위해 반복하도록 요청하지 마세요. 관찰된 동작을 가설과 분리한 다음, 가능한 원인을 구분하는 증거를 수집하세요. 추측으로 코드를 변경하는 대신 집중된 재현, 대상 검사 또는 디버거를 사용하세요. 원인을 수정하고, 비밀을 노출하지 않고 유용한 진단 정보를 보존하며, 경로를 성공적으로 보이게 하기 위해 오류를 절대 억제하지 마세요. 실패가 부분 상태를 남길 수 있는 경우 누락된 회귀 테스트 범위를 추가하고 관련 복구 동작을 검증하세요.
저장소의 기존 빌드, 테스트, 실행 및 생성 진입점을 사용하세요. 문서화된 전제 조건을 읽고 사람과 CI가 사용하는 것과 동일한 명령을 호출하세요. 두 번째 툴체인을 추가하거나 저장소에 다른 적합한 인터페이스가 있는데 Make를 요구하지 마세요. 일치하는 테스트가 없는 테스트 명령은 증거가 아닙니다.
유용한 기여자 문서를 유지하세요. 코드만으로 설명되지 않는 이유, 불변 조건 및 주요 흐름을 보존하고, 영향을 받는 문서를 업데이트하여 대상 사용자에 맞는 사용자 참조, 튜토리얼 또는 문제 해결 자료를 선택하세요. 변경 사항과 관련 없는 광범위한 문서 재작성을 피하세요.
설계 원칙
정확성은 계약에서 시작됩니다
패턴을 선택하기 전에 반드시 유지되어야 하는 것이 무엇인지 정의하세요. 적절한 타입, 생성자 및 명시적인 상태 전환을 사용하여 잘못된 상태를 표현하기 어렵게 만드세요. 변경 가능한 상태와 리소스 수명의 소유권을 명확히 유지하세요.
신뢰할 수 없는 입력은 경계에서 검증하세요. 방어적으로 보인다는 이유만으로 검사를 제거하지 마세요. 조건이 불가능한지, 이미 보장되었는지, 아니면 여전히 실제 실패 모드인지 확인하세요. 비밀을 누출하지 않고 유용한 오류 컨텍스트를 보존하세요. 실패를 조작된 성공 결과로 바꾸지 마세요.
단순성: KISS와 YAGNI
KISS는 단순히 라인 수가 아닌 유지보수자가 이해해야 하는 복잡성을 최소화하는 것을 의미합니다. YAGNI는 추측성 미래 기능보다는 현재 요구사항을 구현하는 것을 의미합니다. 둘 다 누락된 오류 처리, 안전하지 않은 저장소 또는 유지보수 불가능한 지름길을 용납하지 않습니다.
현재 필요 없이 플러그인, 일반 프레임워크, 구성 레이어 또는 확장 지점을 피하세요. 단순한 설계는 나중에 변경을 저렴하게 만드는 명확한 경계를 가질 수 있습니다.
시스템 전반의 복잡성
필수 복잡성(문제에 필요한), 선택적 복잡성(비용이 드는 기능) 및 우발적 복잡성(지정된 동작 구현에서 피할 수 있는 어려움)을 구분하세요. 이를 기능 할당량이 아닌 추론 범주로 사용하세요. 구현, 인터페이스, 통합 및 사용자의 노력과 오류 위험 전반에 걸쳐 적용하세요. 한 곳에서 비용을 낮추면 다른 곳으로 이동할 수 있습니다. 우발적 복잡성은 제거하세요. 선택적 기능은 전체 수명 비용이 사용자 가치를 정당화할 때 유지하세요. 마감일이 임박한 경우 지금의 전달 가치를 종단 간 노력, 지원 및 유지보수와 비교하세요. 더 적은 라인 또는 기능만으로는 더 낮은 총 비용이 확립되지 않습니다. 예시는 복잡성, 인터페이스 및 성능을 참조하세요.
응집도, 결합도 및 정보 은닉
동일한 이유로 변경되는 코드를 그룹화하고, 독립적으로 변경되는 관심사를 분리하세요. 변동성이 큰 구현 선택을 작고 일관된 인터페이스 뒤에 숨기세요. 일련의 통과 래퍼보다 유용한 작업을 수행하는 깊은 모듈을 선호하세요.
인터페이스는 공유 메커니즘이 식별 가능한 호출자에게 서비스를 제공할 수 있고 한 호출자의 정책을 포함하지 않을 때 어느 정도 범용적일 수 있습니다. 현재 사용 사례가 정당화하는 것보다 더 일반적으로 만들지 마세요. 추측된 미래 필요는 현재 호출자에게 부담이 될 수 있습니다. 계약이 실제로 특정한 경우 전문화된 인터페이스를 선택하세요.
단일 책임은 클래스당 하나의 메서드가 아니라 변경에 대한 일관된 이유와 관련이 있습니다. 낮은 결합도는 소비자가 내부에 대해 거의 알지 못해도 된다는 의미이지, 모든 호출이 인터페이스를 요구한다는 의미가 아닙니다. 의존성 방향을 명시적으로 유지하고 가능한 경우 순환을 피하세요.
추상화와 DRY
DRY는 모든 유사해 보이는 시퀀스를 제거하는 것이 아니라 지식의 권위 있는 표현 하나를 의미합니다. 호출자가 동일한 규칙을 표현하고 함께 발전해야 할 때 로직을 공유하세요. 표면적으로 유사한 코드는 서로 다른 개념이나 수명 주기에 속할 때 분리하여 유지하세요.
지식이 생성된 파일에도 나타나는 경우, 권위 있는 소스와 생성기를 식별하세요. 재생성 전에 관련 없는 편집을 보호하세요. 사용자 작업을 덮어쓰지 않고 중복 소유권을 해결하세요. 소스를 업데이트하고, 기존 생성기를 실행하고, 파생된 diff를 검사하세요. 지속적인 수정으로 생성된 출력을 직접 편집하지 말고, 사소한 작업을 위해 생성 메커니즘을 추가하지 마세요.
추출하기 전에 공유 계약, 예상되는 변경 이유, 추상화가 제거하는 복잡성을 식별하세요. 수치적 반복 임계값을 증거로 사용하지 마세요. 약간의 중복은 잘못된 결합보다 비용이 적게 들 수 있습니다.
진단 질문으로서의 SOLID
설계에 도움이 되는 곳에서 이러한 질문을 사용하세요. 절차적 또는 함수형 코드에 객체 지향 아키텍처를 강요하지 마세요.
- 단일 책임: 이 단위가 독립적으로 변경되는 관심사를 혼합하고 있습니까?
- 개방/폐쇄: 가상의 확장 프레임워크가 아니라 격리할 가치가 있는 입증된 변형 축이 있습니까?
- 리스코프 치환: 한 구현이 더 강한 전제 조건, 약한 보장 또는 호환되지 않는 실패를 통해 호출자를 놀라게 하지 않고 다른 구현을 대체할 수 있습니까?
- 인터페이스 분리: 소비자가 사용하는 기능에만 의존합니까?
- 의존성 역전: 안정적인 정책이 변동성이 큰 I/O 세부 사항 대신 좁은 계약에 의존해야 합니까? 함수 또는 매개변수가 그 연결점을 제공할 수 있습니다. 클래스 계층 구조는 필요하지 않습니다.
상속이 진정한 대체 가능 관계를 모델링하지 않는 경우 상속보다 구성을 선호하세요. 목표로서 패턴 이름보다는 언어 관용적 메커니즘을 사용하세요.
가독성과 최소 놀람
도메인 의미, 단위 및 소유권을 드러내는 이름을 선택하세요. 제어 흐름과 부작용을 따라가기 쉽게 유지하세요. 주석은 명백한 설명을 서술하는 것이 아니라 근거, 제약 조건 및 명확하지 않은 보장을 위해 사용하세요.
저장소 규칙이 구체적인 문제를 일으키지 않는 한 따르세요. 함수 크기, 매개변수 수 및 중첩 깊이는 경고 신호이지 보편적인 숫자 제한이 아닙니다. 추가적인 간접 참조가 자동으로 더 깔끔한 코드를 의미하지는 않습니다. 주석은 근거, 제약 조건 및 코드만으로 설명되지 않는 추상화를 보존할 수 있습니다. 길이나 주석 개수 규칙을 충족하기 위해 응집력 있는 로직을 제거하거나 분할하기보다는 컨텍스트에서 그 가치를 판단하세요.
의존성과 성능
어렵고 확립된 기능, 특히 암호화 및 프로토콜 처리를 위해 유지 관리되는 적절한 라이브러리를 재사용하세요. 적합성, 보안, 라이선스, 호환성, 운영 비용 및 의존성 무게를 평가하세요. 언어 또는 저장소에서 이미 제공하는 사소한 작업을 위해 의존성을 추가하지 마세요.
예상 입력 크기에 맞는 적절한 데이터 구조와 알고리즘을 선택하세요. 명백한 중복 작업과 낭비적인 할당 또는 복사를 피하세요. 복잡한 최적화 전에 의심되는 병목 현상을 측정하세요. 대표적인 워크로드를 벤치마킹하고 정확성을 보호하세요. 워크로드, 메트릭, 기준선, 목표 및 중지 기준의 이름을 지정하세요. 활동 횟수가 아닌 실제 사용자 또는 시스템 결과에 연결된 측정을 사용하세요. 계약이 충족되거나 추가 이득이 추가된 복잡성 및 유지보수 비용을 정당화하지 못하면 중지하세요. 계약이 지연 시간, 처리량 또는 리소스 사용 중 무엇을 중요시하는지 결정하세요. 일괄 처리는 응답 시간을 악화시키면서 처리량을 향상시킬 수 있습니다. 명시된 지연 시간 또는 메모리 요구 사항을 스타일적 단순성을 위해 희생하지 마세요. 예시는 복잡성, 인터페이스 및 성능을 참조하세요.
실제 유닉스 철학
한 가지 일을 잘 수행하고 명시적 계약을 통해 구성되는 응집력 있는 컴포넌트를 작성하세요. 이것이 함수당 하나의 프로세스, 마이크로서비스, 텍스트 전용 저장소 또는 모든 곳에서의 무상태성을 요구하지는 않습니다. 명확한 API를 가진 내부 라이브러리도 동일하게 구성 가능할 수 있습니다.
- 메커니즘을 정책과 분리하세요. 재사용 가능한 계산을 표현, 환경 및 변화하는 비즈니스 선택과 분리하여 결합도를 낮추세요.
- 구성을 위해 설계하세요. 숨겨진 전역 상태와 불필요한 하드코딩된 경로를 피하세요. 의존성과 효과를 명시적으로 만드세요. 적절한 경우 호출자가 대상을 선택할 수 있게 하세요.
- 검사 가능한 표현을 선호하세요. 간단한 데이터 구조와 문서화된 형식을 사용하세요. 텍스트는 상호 운용 가능한 도구에 유용합니다. 바이너리 형식은 충실도, 볼륨 또는 성능이 요구될 때 유효합니다.
- 일반 작업은 조용하게, 실패는 가시적으로 유지하세요. 침묵은 관련 없는 잡음이 없음을 의미하며, 결과 데이터가 누락되거나 진단이 억제된 것을 의미하지 않습니다.
- 도구를 재사용하세요. 기존의 신뢰할 수 있는 기능을 재구축하는 것보다 선호하세요. 스크립트용으로 의도된 경우 자동화를 비대화형으로 유지하세요.
인터페이스 스타일은 전통이 아닌 인간 및 기계 소비자에 의해 선택하세요. 함수 또는 라이브러리 API, 안정적인 CLI 또는 필터는 기계 호출자와 반복 가능한 작업에 적합할 수 있습니다. 인간의 작업은 발견 가능성, 피드백 또는 직접 상호 작용이 필요할 수 있습니다. 둘 다 실제 소비자인 경우 도메인 로직을 선택적 래퍼와 분리하여 GUI를 필수로 만들지 않고 동작을 공유하세요. 계약을 충족하는 가장 간단한 스타일을 따르세요. 실용적인 트레이드오프는 유닉스 인터페이스 및 복잡성, 인터페이스 및 성능을 참조하세요.
CLI, 파이프라인 및 구성 설계에 대해서는 유닉스 인터페이스를 읽으세요. 복잡성, 인터페이스 스타일 또는 성능 트레이드오프가 결정을 실질적으로 형성하는 경우 복잡성, 인터페이스 및 성능을 읽으세요. 경쟁 원칙 및 예시에 대해서는 트레이드오프를 읽으세요. 이러한 참조는 조건부입니다. 관련 없는 로컬 편집에 대해 필수 사항이 아닙니다.
실용적인 디버깅, 프로젝트 명령, 생성된 아티팩트, 유지보수자 문서 및 의존성 평가 예시에 대해서는 디버깅 및 유지보수를 읽으세요.
안전한 진화와 검증
리팩터링은 출력, 오류, 부작용 및 소비자가 의존하는 계약을 포함한 관찰 가능한 동작을 보존합니다. 리팩터링 중에 특이점을 조용히 수정하지 마세요. 의도적인 계약 변경은 대신 영향을 받는 테스트와 소비자를 명시적으로 업데이트합니다. 대체된 요구 사항의 테스트는 영구적인 제약 조건이 아닙니다.
동작 중심 테스트로 공개 경계를 보호하세요. 적절한 테스트 범위를 재사용하세요. 중요한 경로가 보호되지 않은 경우 회귀 또는 특성화 테스트를 추가하세요. 실용적인 경우 실제 구현 또는 집중된 페이크를 선호하지만, 진정으로 비용이 많이 들고, 비결정적이거나, 안전하지 않은 경계를 격리하기 위해 더블을 사용하세요. private 메서드 호출 또는 정확한 소스 표현(그 자체가 계약인 경우가 아니라면)에 대한 단언을 피하세요.
의미 있는 엣지 케이스를 확인하세요. 잘못된 입력, 빈 데이터, 리소스 실패 및 관련이 있는 경우 동시성 또는 부분 쓰기. 모든 편집에 대해 임의의 테스트 범위 백분율 또는 전체 테스트 스위트를 규정하지 마세요.
변경 범위에 포함되지 않는 한 공개 호환성을 유지하세요. 내구성 있는 계약 및 지속된 데이터의 경우 소비자, 배포 순서, 마이그레이션 및 복구를 검사하세요. 이전 버전과 새 버전이 공존해야 하는 경우 확장/축소 또는 다른 단계적 접근 방식을 사용하세요. 그렇지 않으면 조정된 원자적 변경으로 충분할 수 있습니다. 실제 요구 사항 없이 복구 경로를 삭제하거나 호환성 심을 설치하지 마세요.
최종 결정 확인
완료를 선언하기 전에 다음을 질문하세요.
- 구현이 관련 실패를 포함하여 실제 계약을 충족합니까?
- 각 추상화, 의존성 및 변경된 파일이 이 작업에 의해 정당화됩니까?
- 유지보수자가 규칙, 해당 상태 소유자 및 이를 보호하는 증거를 찾을 수 있습니까?
- 기존 동작을 보존했거나 의도된 변경을 영향을 받는 모든 소비자에게 명시적으로 만들었습니까?
- 실제로 무엇을 검증했으며, 무엇이 검증되지 않았습니까?
이 확인은 개인적으로 사용하세요. 모든 편집에 대해 상용구 보고서 또는 원칙 점수를 내보내지 마세요.