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