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