Technote

개발 워크플로우 실무

연재 요구사항을 구조로 바꾸기 8부 중 3부

예외는 QA 가 아니라 명세에서 다룹니다

빈 상태 · 실패 · 권한 없음 · 아주 긴 값. 구현이 의도에서 갈라지는 자리는 거의 항상 이 넷 중 하나이고, 넷 다 명세에서 한 줄이면 끝나는 것들입니다.

기능이 완성되고 QA 가 시작되면 결함 목록이 올라옵니다. 그런데 그 목록을 읽어 보면 상당수가 결함이 아니라 미정입니다. “데이터가 없을 때 화면이 비어 있음”, “저장 실패 시 아무 반응 없음”, “권한 없는 사용자가 접근하면 오류 화면”. 개발자가 틀린 것이 아니라, 그 상황에서 무엇을 해야 하는지 아무도 정해 주지 않은 것입니다.

이 시점의 수정은 비쌉니다. 화면 구조가 이미 만들어졌고, 예외 처리를 넣으려면 그 구조를 다시 열어야 하며, 일정은 이미 QA 단계까지 와 있습니다. 같은 결정을 명세에서 하면 한 줄인데, QA 에서 하면 재작업이 됩니다.

구현이 갈라지는 네 자리

경험적으로 이런 미정은 거의 항상 같은 네 곳에서 생깁니다. 화면 하나를 설계할 때마다 이 넷을 순서대로 물으면 대부분이 미리 닫힙니다.

명세에서 닫아 두는 네 자리 — 화면마다 이 순서로 한 번씩 묻는다

빈 상태는 모든 사용자가 처음에 보는 화면인데도 가장 자주 빠집니다. 데이터가 하나도 없을 때 그냥 텅 빈 표를 보여 줄지, 무엇을 하면 되는지 안내와 버튼을 둘지가 여기서 갈립니다. 신규 사용자가 처음 만나는 화면이라 첫인상을 통째로 결정합니다.

실패는 “성공하면” 만 적힌 명세의 반대편입니다. 실패했을 때 사용자가 입력한 내용이 남아 있는지, 다시 시도할 수 있는지, 무엇이 잘못됐는지 알 수 있는지를 적습니다. 특히 입력값이 사라지는지는 반드시 정합니다 — 긴 폼을 다시 채우게 만드는 것은 실패보다 나쁜 경험입니다.

권한 없음은 로그인하지 않은 사람, 다른 조직의 사용자, 이미 로그아웃된 사람이 주소를 직접 열었을 때입니다. 로그인 화면으로 보낼지, 없는 페이지처럼 보일지, 안내를 띄울지는 보안과도 관련이 있어 개발자가 임의로 정하면 안 되는 항목입니다.

아주 긴 값은 디자인 시안에는 절대 등장하지 않는 데이터입니다. 시안의 제목은 언제나 한 줄에 예쁘게 들어갑니다. 실제 데이터에서는 두 줄, 세 줄이 되고 그때 레이아웃이 어떻게 되는지를 미리 정해야 합니다.

한 줄이면 충분합니다

예외를 적는다고 문서가 두 배가 되지는 않습니다. 상황마다 한 줄이면 됩니다.

예외 명세의 실제 분량 — 화면 하나에 다섯 줄이면 대개 충분하다

정하지 못한 것은 정하지 못했다고 적습니다

모든 예외를 처음부터 정할 수는 없습니다. 그럴 때 빈칸으로 두지 말고 “미정 — 누가 언제까지 정한다” 를 적어 둡니다. 빈칸은 개발자가 임의로 채우게 되고, 그 결정은 문서에 남지 않아 나중에 왜 그렇게 됐는지 아무도 설명하지 못합니다. 미정이라고 적힌 칸은 최소한 모두가 보고 있는 미정입니다.

화면과 데이터의 상태를 설계 단계에서 다루는 글은 개발 워크플로우 아카이브에 더 있고, 이미 만들어진 사이트에서 이런 예외가 어디에 남아 있는지 점검받고 싶다면 최적화 지원 사업의 진단이 상태 점검을 포함합니다.

다음 회차

목적 · 시나리오 · 예외가 모였습니다. 다음 회차는 이것들을 어떤 형식에 담아야 개발자가 다시 묻지 않는지 — 명세 문서의 여섯 칸입니다.

이 주제의 다른 글

노하우 목록으로

개발 워크플로우 실무

스테이징에서 먼저 올려 보는 30분

스테이징은 개발자만 쓰는 장치가 아닙니다. 프로덕션에서 복구하는 데 드는 하루와 스테이징에서 확인하는 30분을 비교하면, 이것은 취향이 아니라 계산입니다.

운영 · 관리자 3분 읽기

개발 워크플로우 실무

자주 울리는 알림은 결국 꺼집니다

알림을 무시하기 시작하면 그 감시는 이미 고장 난 것입니다. 게다가 꺼진 알림은 없는 알림보다 나쁩니다 — 지켜지고 있다는 착각을 남기기 때문입니다.

운영 · 관리자 4분 읽기

개발 워크플로우 실무

도메인 치환 — SQL 한 줄이 설정을 지웁니다

데이터베이스 안의 옛 주소를 SQL 로 바꾸면 위젯과 테마 설정이 조용히 빈 값이 됩니다. 직렬화가 문자열 길이를 함께 저장하기 때문입니다.

운영 · 관리자 4분 읽기

₩270,000 · 신청하기