착수 전에 미해결을 세어 본다

새 인터페이스를 붙이는 작업을 맡았는데 설계 문서가 여럿이고 기존 코드도 있었다. 바로 시작하지 않고 문서가 말하는 것과 코드에 있는 것을 대조했다.

Open Table of contents

문서와 코드를 대조한 여섯 항목

대조에서 미해결이 여섯 개 나왔다. 문서 안에서 프로토콜 버전 값이 모순이고 라이브러리 선택이 미결이고 문서에서 도출한 엔드포인트 목록이 실제 등록분과 열 개 넘게 달랐다.

나머지 셋은 구조 쪽이었다. 문서가 말하는 계층이 코드에 없고 권한 범위와 역할 사이 매핑이 설계에도 코드에도 없고 특정 알림을 보내는 데 필요한 세션 목록이 아예 없었다.

넷째가 가장 컸다. 문서는 핵심 로직이 전송 방식에 중립적인 계층에 있으므로 새 인터페이스는 그 계층을 부르면 된다고 적고 있었다.

실제로는 로직이 요청 핸들러 본문에 그대로 들어 있었고 파싱과 처리와 응답 생성이 한 함수 안에 있었다. 문서만 읽고 착수했으면 호출만 하면 된다고 견적을 내고 여든 개 넘는 핸들러를 뜯는 작업을 만났을 것이다.

이 조사에서 문서가 낡는 방식이 몇 갈래로 보였다. 추가는 반영되고 삭제는 안 반영되어 없어진 엔드포인트가 목록에 남아 있었다.

계획이 현재형으로 적혀 사실처럼 읽히는 것도 있었고 여러 문서가 같은 것을 다르게 말하면서 어느 쪽이 최신인지 표시가 없었다. 정본이 문서에서 코드로 옮겨 갔다는 사실을 아무도 안 적은 것이 넷째였다.

여섯 개를 전부 닫고 시작하면 착수가 한참 늦어진다. 그래서 전체 표면 중 네 개만 먼저 붙이는 작은 수직 슬라이스로 갔다.

그렇게 하니 여섯 중 실제로 막히는 것만 만났다. 계층 추출은 그 네 개에 해당하는 부분만 꺼냈고 권한 매핑도 그 네 개에 필요한 범위만 정의했으며 나머지 넷은 이번에 만나지 않았다.

작업이 끝나고 남은 실질은 코드가 아니라 미해결 목록이었다. 각 항목마다 무엇이 미결이고 이번에 어디까지 처리했는지를 붙여 적었다.

다음 사람이 표면을 확장할 때 이 목록부터 보면 같은 대조를 처음부터 다시 하지 않아도 된다. 조사에서 나온 것을 목록으로 남기지 않으면 조사 자체가 일회용이 된다.