지적받은 것을 문서에 먼저 반영했다

쿠폰 기능 설계를 보이고 지적을 받았다. 코드를 고치고 넘어갔더니 나중에 문서와 안 맞았다.

Open Table of contents

문제 — 지적의 내용
코드만 고치고 넘어갔다
두 달 뒤에 문제가 됐다
문서를 먼저 고치기로 했다
지적 목록과 반영 순서
정리

문제 — 지적의 내용

설계는 이렇게 적혀 있었다.

쿠폰 사용 설계

1. 회원이 쿠폰을 고른다
2. 할인 금액을 계산한다
3. 주문에 적용한다
4. 쿠폰을 사용 처리한다

주문이 실패하면 쿠폰은 어떻게 되느냐는 지적을 받았다. 4번이 3번 뒤에 있어서 주문이 실패해도 쿠폰이 쓰인 것으로 남을 수 있는 순서였다.

코드만 고치고 넘어갔다

한 트랜잭션에 넣었다.

$this->db->trans_start();
$orderNo = $this->order->create($data);
$this->coupon->use($couponNo, $orderNo);
$this->db->trans_complete();

trans_start 와 trans_complete 사이에 둘을 넣으니 주문이 실패하면 쿠폰도 안 쓰인다. 고치고 svn commit 하고 넘어갔고 문서는 그대로 뒀다.

두 달 뒤에 문제가 됐다

다른 사람이 그 문서를 보고 취소 기능을 만들었다.

문서: 4. 쿠폰을 사용 처리한다

취소할 때 되돌리는 것이 문서에 없어서 안 만들었다. 취소해도 쿠폰이 안 돌아왔다.

고친 것이 문서에 없으니 다음 사람은 지적 전 설계를 봤다. svn log 에도 코드 수정만 있고 문서는 그 리비전에 없었다.

문서를 먼저 고치기로 했다

문서부터 고쳤다.

쿠폰 사용 설계 (2014-12 수정)

1. 회원이 쿠폰을 고른다
2. 할인 금액을 계산한다
3. 주문 생성과 쿠폰 사용을 한 트랜잭션으로 처리한다
   - 주문이 실패하면 쿠폰도 사용되지 않는다
4. 주문 취소 시 쿠폰을 되돌린다
   - 단, 쿠폰 유효기간이 지났으면 되돌리지 않고 사유를 남긴다

4번은 문서를 고치면서 나온 것이었고 코드에도 없었다. 문서를 고치다가 빠진 것을 발견한 셈이다.

지적은 대개 한 문장이지만 문서에 반영하려면 어디에 어떻게 넣을지 정해야 한다. 그 과정에서 영향 범위가 보이고 코드만 고치면 그 자리만 보고 끝난다.

지적 목록과 반영 순서

말로 들은 지적은 사라지므로 적었다.

2014-12-25 쿠폰 설계 검토

지적 1  주문 실패 시 쿠폰 상태     → 트랜잭션으로 묶음. 문서 3항 수정
지적 2  중복 사용 방지 방법        → 유일 인덱스 추가. 문서에 추가
지적 3  유효기간 판정 시점         → 주문 시점 기준. 문서에 명시

무엇을 지적받고 어떻게 했는지가 남으니 나중에 이건 왜 이렇게 했는지에 답이 된다. 지적 2는 사용 이력에 UNIQUE KEY 를 걸고 UPDATE ... WHERE used = 0 의 ROW_COUNT() 로 판정하게 고친 것이었다.

세 번째 지적이 컸다. 유효기간 판정을 언제 기준으로 하느냐였다.

주문한 시점    12/25 23:58
결제 완료      12/26 00:03
쿠폰 만료      12/25 24:00

주문 시점이면 되고 결제 시점이면 안 되는데 정해진 것이 없어서 물어보고 주문 시점으로 정해 문서에 적었다.

// 쿠폰 유효기간은 주문 생성 시점 기준으로 본다 (2014-12 결정)
if ($coupon['expire_date'] < $order['reg_date']) { ... }

코드에도 한 줄 적었다. 어느 쪽이든 되는 것처럼 보이는 자리라 근거가 필요했다.

그래서 순서를 정했다 — 지적을 목록에 적고 문서를 고치고 코드를 고치고 목록에 처리 결과를 적는다.

문서가 어디 있는지도 문제였다. 메신저로 주고받은 파일과 공유 폴더에 있는 것이 서로 달랐고 파일 이름의 날짜가 만든 날인지 고친 날인지도 제각각이었다. docs/coupon-design.md 로 저장소에 옮겨 코드와 같은 svn commit 에 묶이게 했다. 메신저로는 링크만 보냈다. 문서와 코드가 한 리비전에 있으면 둘이 어긋날 자리가 없다.

정리

지적받은 것을 코드만 고치면 문서가 낡는다
낡은 문서를 보고 다음 사람이 지적 전 설계로 만든다
svn log 에 코드만 있으면 문서는 그 리비전에 없다
문서를 먼저 고치면 고치다가 빠진 것이 드러난다
말로 들은 지적은 사라지므로 목록으로 적는다
무엇을 지적받고 어떻게 했는지 남기면 왜 이렇게 했는지에 답이 된다
어느 쪽이든 되어 보이는 자리는 정하고 코드에도 근거를 적는다
문서를 docs/ 에 두어 코드와 같은 리비전에 묶는다