찾기 쉬운 API와 실제 값 테스트를 갖춘 데이터 처리 라이브러리 만들기

## 복잡한 원본 데이터를 단순한 객체 뒤에 숨기기 중요한 기능을 숨기지 않으면서 원본 형식의 복잡성을 직관적인 도메인 객체 뒤에 감춘다. 일반적인 작업은 바로 수행할 수 있게 하고, 전문적인 구문 분석, 보고서 생성, 검사 기능은 사용자가 필요로 할 때 단계적으로 제공한다. 쓰기 전에 읽는다. 코드를 수정하기 전에 기존 추상화, 명명 패턴, 모듈 경계, 주변 테스트를 살펴본다. 구체적인 비호환성 때문에 새 패턴이 필요한 경우가 아니라면 기존 설계를 확장한다. ## 편집 전에 어느 모듈이 무엇을 맡는지 정리하기 사용자의 요구를 담당 모듈과 주요 도메인 클래스에 연결하는 간결한 탐색 지도를 유지한다. 레코드 찾기, 엔티티 불러오기, 구조화 데이터 구문 분석, 명세서 작성, 주석 읽기, 문서 열기, 타입이 지정된 보고서 생성을 위한 공개 진입점을 포함한다. 편집하기 전에 대표적인 데이터 흐름을 처음부터 끝까지 추적한다. 요청이 공개 진입점에서 시작해 데이터 가져오기, 구문 분석, 타입이 지정된 객체, 명세서, 주석, 보고서, 문서 추출을 거치는 과정을 따라간다. 각 변환을 어느 계층이 담당하는지, 사용자가 뒷받침하는 세부 정보로 어디에서 더 깊이 들어가야 하는지 확인한다. 이 지도를 사용해 책임을 맡는 가장 작은 모듈을 선택한다. 다른 계층이 이미 해당 책임을 맡고 있다면 단지 편리하다는 이유로 다른 파일에 동작을 배치하지 않는다. ## 큰 파일은 조금씩 읽고 고치는 범위를 좁히기 30 KB보다 큰 모듈은 하나의 블록으로 읽거나 다시 작성하지 말고 여러 개의 국소적 맥락으로 취급한다. 관련 기호를 검색하고, 기호를 포함하는 클래스나 함수를 살펴본 다음, 불변 조건과 호출 위치를 이해하는 데 필요한 만큼 주변 코드를 읽는다. 큰 파일을 변경하기 전에 관련 테스트, import, 하위 클래스, 공개 참조를 찾는다. 변경 범위를 좁게 유지하고 주변 규칙을 보존하며, 기능 변경을 가릴 수 있는 관련 없는 재서식 지정이나 구조 변경을 피한다. ## 작업을 이슈에 기록하고 상태를 갱신하기 프로젝트의 이슈 관리 시스템을 진행 중인 작업의 영속 기록으로 사용한다. 열려 있거나 진행 중인 항목을 검토하고 관련 이슈를 선택한 뒤, 구현 전에 활성 상태로 옮긴다. 새로 발견한 결함이나 작업은 주석 또는 채팅에만 남겨 두지 말고 명확한 제목, 유형, 우선순위와 함께 기록한다. 범위, 방해 요소 또는 결론이 달라지면 같은 이슈를 업데이트한다. 필요한 검증이 끝난 뒤에만 이슈를 닫는다. 정의된 `open`, `in-progress`, `blocked`, `closed` 상태를 유지한다. 추적 시스템이 5단계 우선순위를 사용한다면 `0`은 긴급 작업, `4`는 대기 작업에 그대로 사용하고 임의의 레이블을 만들지 않는다. ## 라이브러리가 문서의 약속대로 동작하는지 확인하기 검증은 내부 코드가 단순히 실행되는지가 아니라 라이브러리가 문서에서 약속한 내용을 제공하는지를 묻는다. 다음 세 가지 원칙을 적용한다. 1. 문서는 명세이므로 문서화된 모든 예제를 검증할 수 있어야 한다. 2. 데이터 정확성은 필수이므로 검사는 단순한 존재 여부가 아니라 구체적인 예상값을 단언해야 한다. 3. API는 문제를 해결할 수 있어야 하므로 사용자와 에이전트는 질문에서 적절한 객체, 메서드, 뒷받침 근거까지 찾아갈 수 있어야 한다. 이 원칙들을 사용하여 기능 설계, 문서, 테스트 사례, 실패 동작을 함께 평가한다. ## 새 기능마다 실제 값 테스트와 실행되는 문서 예제 붙이기 새로운 사용자 대상 기능은 반드시 다음을 포함해야 한다. - 독립적으로 확인한 실제 원본 레코드의 구체적인 값을 사용하는 기준 사실 단언 한 가지 - 자동 검증으로도 실행되는 문서화된 예제 한 가지 - 유효하지 않거나 누락된 입력이 빈 값 또는 알림 없는 실패가 아니라 유용한 오류를 생성함을 증명하는 조용한 실패 검사 한 가지 - 기능을 프로젝트 탐색, 기능 카탈로그 또는 에이전트 지침에 표시하는 검색 가능성 업데이트 한 가지 정상 경로의 구현이 작동하더라도 이 요소 중 하나라도 빠지면 해당 기능은 완료되지 않은 것이다. ## 빠른 로컬 테스트를 먼저, 네트워크 테스트는 하나씩 실행하기 빠른 로컬 검증, 네트워크 기반 검증, 회귀 검증, 커버리지 보고를 위한 명령을 각각 제공한다. 먼저 관련된 최소 로컬 검사를 실행하고, 집중된 결과가 통과한 경우에만 범위를 넓힌다. 외부 서비스에 접속하지 않는 빠른 테스트만 병렬로 실행한다. 네트워크 검증은 순차적으로 실행하고 서비스의 요청 속도 제한을 준수한다. 검증 대상 계약을 가리지 않으면서 외부 동작을 빠르고 결정적으로 만들 수 있다면 기록된 응답 픽스처를 사용한다. 회귀 사례는 각 사례를 원인이 된 결함과 연결하는 안정적인 이름으로 전용 영역에 배치한다. 커버리지는 보조 근거로 취급하며, 동작과 데이터에 대한 단언을 대신하게 하지 않는다. ## 다양한 원본 데이터로 정확한 값과 분명한 오류 확인하기 정확한 도메인 값, 정규화된 구조, 의미 있는 오류 메시지를 단언한다. 정확성이 값 자체에 달려 있다면 결과가 존재한다는 사실만 확인하는 단언으로는 충분하지 않다. 익숙한 예제 하나에만 의존하지 말고 조직, 산업, 형식, 보고 기간이 서로 다른 원본 레코드를 사용한다. 형식이 잘못되거나 불완전하거나 지원되지 않는 입력을 명시적으로 시험한다. 실패 시 실행 가능한 조치를 알려 주는 메시지가 반환되고, 아무 알림 없이 빈 결과로 바뀌지 않는지 확인한다. 외부 데이터가 필요하면 결정적인 픽스처를 보존하고 예상값을 어떻게 정했는지 문서화한다. 상위 계약이 바뀔 때는 의도적으로 픽스처를 업데이트하며, 실패한 검사를 통과시키기 위한 목적으로만 갱신하지 않는다. ## 버전과 문서를 동작하는 코드와 어긋나지 않게 유지하기 지정된 메타데이터 파일에서 프로젝트 버전을 읽고, 관련 없는 모듈에 버전을 중복해서 두지 않는다. 저장소 탐색, 검증 지침, 공개 예제, 기능 카탈로그를 지원되는 동작과 동기화한다. API 경로가 바뀌면 같은 작업 항목에서 문서와 실행 가능한 예제를 업데이트한다. 대체 구현이 정확하더라도 문서화된 경로가 더 이상 실행되지 않는다면 사용자 대상 계약이 깨진 것이다.