한 업체가 상품 가져오기 화면에서 category_id와 배송정책이 공란이고 배송정책 <select>가 아예 없다는 문의를 넣었다. ImportController를 열어 보니 delivery_policy_id를 다루는 코드가 전혀 없었다.
Table of contents
Open Table of contents
원인 — 생략을 적어 둔 주석
그 자리 위에 주석이 있었다. options를 넘기면 내부에서 배송정책의 shipping_from을 참조하는데 이 경로의 마스터상품은 배송정책이 없으므로 options 없이 createProduct()만 부른다는 내용이었다.
의도가 적혀 있었으므로 빠뜨림이 아니라 설계였다. 주석이 없었으면 빠뜨린 것으로 보고 넣으려 했을 것이고 넣으면 null인 shipping_from을 참조해 터진다.
판단 기준 — 좋은 주석의 세 요소
이 주석이 왜 값어치를 했는지를 정리하면 셋이다. 무엇을 안 하는지와 왜 안 하는지와 어디를 봐야 하는지를 적었다.
안 한 것에 대한 주석이라는 점이 핵심인데 코드에 없는 것은 코드를 봐도 알 수 없기 때문이다. 빠뜨림과 의도적 생략을 구분해 주는 것이 주석이 할 일이다.
조치 — 안내와 확장 비용
두 가지 방법이 있었는데 그 경로에 배송정책 선택을 넣어 주는 것과 버그가 아니므로 안내로 처리하는 것이다. 뒤쪽을 골랐다. 이유는 넣으려면 옵션 생성 경로를 새로 짜야 해서 문의 하나로 시작할 크기가 아니라서다. 대신 업체가 두 단계를 손으로 밟는 불편을 감수했다. 가져오기 화면에서 category_id만 선택해 상위 상품을 등록하고 등록된 상위 상품에서 delivery_policy_id를 직접 설정하는 두 단계다.
자동으로 되게 해 달라는 요청이 나올 수 있어서 무엇이 필요한지도 함께 적었다. delivery_policy_id를 먼저 만들거나 고르게 하고 그것을 참조하는 createOption() 경로를 추가한 뒤 기존 경로와 if로 분기해야 한다. 안 된다고 답하지 않고 이만큼 필요하다고 답하면 요청한 쪽이 우선순위를 정할 수 있다.
상황 — 오인의 원인
왜 이런 문의가 나왔는지도 봤다. 이 업체는 옛 버전 시절 이름이 비슷한 베타 기능을 수년간 써서 수백 건을 가져왔다.
그 베타 기능은 다르게 동작했을 것이고 신 버전 기능을 그것과 같은 것으로 오인한 것이다. 이름이 비슷하면 같은 것으로 여기므로 안내에 이전에 쓰던 기능과 동작이 다르다는 것을 명시했다. 원래 그렇다는 말보다 달라졌다는 말이 받아들여지는데 사용자 쪽에서는 되던 것이 안 되는 상황이기 때문이다.
교훈 — 주석이 없었을 경우
이 조사가 짧게 끝난 것은 주석 덕이었다. 주석이 없었으면 delivery_policy_id 처리를 찾다가 없다는 것을 확인하고 왜 없는지 모른 채 넣어 봤다가 null 참조로 터진 뒤에야 발견했을 것이다.
몇 배가 걸렸을 것이고 중간에 운영을 터뜨렸을 수도 있다. 의도적 생략에 이유를 적는 주석 몇 줄이 그 경로 전체를 막는다.
정리
- 화면에 항목이 없는 것이 빠뜨림이 아니라 설계일 수 있다
- 안 한 것에 대한
//주석이 값어치가 크다 - 코드에 없는 것은 코드를 봐도 모른다
- 좋은
//주석은 무엇을 왜 안 하는지와 어디를 볼지를 적는다 - 버그가 아니면 안내 절차를 준다
- 안 된다가 아니라 이만큼 필요하다고 답한다
- 이름이 비슷하면 같은 것으로 여긴다
- 원래 그렇다보다 달라졌다가 받아들여진다