주석을 보고 동작을 이해했는데 실제 코드가 달랐다. 재고가 부족하면 주문을 거부한다고 적혀 있었지만 코드는 알림만 보내고 그대로 통과시키고 있었다.
Table of contents
Open Table of contents
언제 갈렸는지
이력에서 그 줄을 추적하니 재작년에 예외를 던지던 것을 알림 발송으로 바꾸면서 주석을 안 고친 것이었다. 당시에는 재고 자료가 부정확해서 거부하면 정상 주문이 막히는 문제가 있었다.
바꾼 이유는 맞았는데 주석이 따라가지 않았다. 주석을 고치면서 지금 동작과 그 이유를 적고 다시 볼 조건까지 넣었는데 그것을 안 적으면 왜 이런지 모르는 채로 남기 때문이다.
표본으로 잰 오류율
다른 주석도 확인하려니 서비스 계층에만 400여 개가 있어서 전부 볼 수 없었다. 동작을 설명하는 형태만 골라내니 88개였고 그중 스물을 표본으로 봤다.
넷이 틀렸고 둘이 애매해서 오류율이 20퍼센트였다. 왜 틀렸는지도 보니 대부분 코드를 고치고 주석을 안 고친 것이었다. 표본을 세지 않았으면 주석 하나가 틀렸다는 사실만 남고 전체가 얼마나 믿을 만한지는 몰랐을 것이다.
이름으로 드러내기
틀릴 수 있는 주석 자체를 줄이는 쪽도 했다. 무엇을 하는지 설명하던 주석은 함수 이름을 정확히 바꾸니 필요 없어졌다.
항상 참만 돌려주는 반환값도 이상해서 돌려줄 것이 없으면 안 돌려주게 했다. 이름이 맞으면 주석이 덜 필요하고 덜 틀린다.
없앨 것과 남길 것
그래서 두 종류를 갈랐다. 무엇을 하는지는 이름으로 드러내 없애고 왜 그렇게 하는지는 코드로 표현이 안 되므로 남긴다.
재고 자료가 부정확해서 거부하지 않는다는 것은 이름으로 표현할 수 없으므로 남겼다. 주석에 날짜를 적는 것도 넣었는데 언제 적은 것인지 알면 얼마나 낡았는지를 가늠할 수 있어서 오래된 주석은 의심하고 코드를 읽게 된다.
문서까지 이어지는 갈림
주석만이 아니라 문서도 코드와 갈려 있었다. 같은 내용이 문서에도 적혀 있었고 둘 다 안 고쳐진 상태였다.
그래서 코드를 고칠 때 같이 봐야 할 것을 목록으로 파일 위에 적어 뒀더니 고칠 때 눈에 들어왔다. 같은 내용이 세 곳에 있다는 것을 알고 나서 줄일 수 있는지도 봤고 운영 안내 쪽은 코드에서 뽑아 만들 수 있었다. 같은 사실이 여러 곳에 적혀 있으면 갈리는 것은 시간문제이므로 줄일 수 있는 곳을 먼저 줄인다.
정리
- 주석을 믿고 코드를 안 읽으면 틀린 전제로 간다
- 코드를 고치고 주석을 안 고치는 것이 대부분이다
- 표본으로 확인하면 전체가 얼마나 틀렸는지 나온다
- 검토할 때 주석도 본다
- 이름으로 드러내면 주석이 덜 필요하고 덜 틀린다
- 무엇을 하는지는 없애고 왜 그런지는 남긴다
- 주석에 날짜를 적으면 얼마나 낡았는지 알 수 있다
- 같은 사실이 여러 곳에 있으면 줄일 수 있는 곳을 줄인다