주석을 믿고 설계했습니다

안녕하세요. 오픈소프트랩 개발팀입니다.

기능을 고치기 전에 설계 문서를 먼저 작성합니다. 지금 코드가 어떻게 동작하는지 적고, 무엇을 바꿀지와 그 근거를 붙입니다.

그 문서의 초판이 틀렸던 이야기입니다.

주석은 코드를 설명한다고 봤습니다

고치려던 건 차단된 요청을 기록하는 부분이었습니다. 어떤 요청이 정책에 걸려 막혔을 때, 그 사실을 분석 결과 쪽에 남기는 코드입니다.

문서를 쓰려면 지금 동작을 먼저 알아야 합니다. 코드를 읽었고, 거기 달린 주석도 같이 읽었습니다.

주석 두 개가 눈에 들어왔습니다.

// 이 메서드는 (특정 모드) 조건 없이 항상 동작한다

<!-- 이 집계는 차단 건수를 대상으로 한다 -->

이 둘을 근거로 초판을 작성했습니다. 차단 기록이 어느 모드에서나 남고, 그게 집계에도 들어간다는 전제였습니다. 그리고 최근 변경으로 그 동작이 한 모드에서만 되게 좁아졌으니, 원래대로 되돌리자는 개선안을 냈습니다.

주석 두 개가 다 틀렸습니다

문서를 검토하는 단계에서 걸렸습니다.

첫 번째 주석. 그 메서드는 조건 없이 동작하는 게 맞았습니다. 다만 그 메서드를 부르는 쪽에 이미 조건이 걸려 있었습니다. 메서드 자체는 아무 데서나 돌 수 있게 생겼지만, 실제로는 조건을 통과한 경로에서만 불립니다.

주석은 메서드의 성질을 적은 것이었고, 저희는 그걸 실제 호출 조건으로 읽었습니다.

변경 이전 코드를 다시 꺼내 봤더니 그때도 마찬가지였습니다. 즉 좁아진 게 아니라 원래부터 그랬습니다. 되돌릴 대상이 애초에 없었습니다.

두 번째 주석. 집계 쿼리를 열어 조건을 직접 확인했습니다. 차단 기록에 붙는 상태값과 집계가 찾는 상태값이 서로 달랐습니다. 차단 건은 처음부터 집계에 들어간 적이 없습니다.

주석이 쓰였을 당시에는 맞았을 수도 있습니다. 그 뒤에 상태값 체계가 바뀌었고 주석은 그대로 남았습니다.

복원인 줄 알았는데 신규 동작이었습니다

두 주석을 걷어내고 나니 개선안의 성격이 달라졌습니다.

초판은 이걸 복원이라고 불렀습니다. 원래 되던 걸 되돌린다는 뜻이니 위험이 낮아 보입니다. 검토하는 사람도 가볍게 봅니다.

실제로는 한 번도 그렇게 동작한 적이 없는 새 동작이었습니다. 게다가 그 기능은 "이 모드에서만 동작한다"는 설계 원칙 아래 있었고, 조건을 풀면 그 원칙을 어기게 됩니다.

같은 변경인데 복원이라고 부르는 순간 통과하기 쉬워집니다. 이름을 잘못 붙인 것이 실제로는 가장 위험했습니다.

그래서 개선안을 폐기했습니다. 문서에 폐기 사유를 남기고, 남은 선택지 둘을 다시 적었습니다. 둘 다 설계 원칙을 지키는 안입니다.

검토 방식을 바꿨습니다

이 일을 겪고 문서 검토 순서를 바꿨습니다.

예전에는 문서를 작성하고 사람이 읽었습니다. 읽는 사람도 코드를 다 열어보지는 않으니, 문서에 적힌 근거가 맞다는 전제로 읽게 됩니다. 문서가 주석을 인용하면 그 주석을 다시 확인하지 않습니다.

지금은 두 가지를 넣었습니다.

하나, 서로 다른 모델 여럿에게 같은 문서를 검토시킵니다. 각자 다른 곳을 지적합니다. 같은 지점을 여럿이 짚으면 대체로 실제 문제였습니다. 이번 건도 그렇게 나왔습니다.

둘, 문서에 적는 근거는 주석이 아니라 원본을 가리키게 했습니다. "주석에 이렇게 쓰여 있다"는 근거가 되지 않습니다. 실제 코드의 어느 줄인지, 쿼리의 어느 조건인지를 적습니다. 확인하는 사람이 한 번에 열어볼 수 있게 하는 것이 목적입니다.

얻은 것과 포기한 것

얻은 것 — 틀린 개선안이 들어가기 전에 멈췄습니다. 그리고 그 과정에서 같은 종류의 진입점 네 곳을 전부 확인했습니다. 원래는 한 곳만 보려던 작업이었습니다.

문서에 폐기한 안과 그 이유를 남긴 것도 남았습니다. 나중에 같은 제안이 다시 올라올 때 처음부터 따지지 않아도 됩니다.

포기한 것 — 시간입니다. 고치려던 것은 못 고쳤고, 확인하는 데만 며칠이 들었습니다. 그 며칠 동안 기능은 그대로였습니다.

검토를 여러 겹으로 두면 통과 속도가 느려집니다. 모든 변경에 이렇게 하지는 않습니다. 설계 원칙을 건드리는 변경에만 적용하고 있습니다.

주석을 어떻게 할 것인가

남은 문제입니다.

가장 단순한 답은 "틀린 주석을 고친다"입니다. 실제로 이번에 발견한 두 개는 고쳤습니다. 그런데 같은 종류가 더 있을 겁니다. 코드베이스 전체의 주석을 검증하는 일은 하지 않기로 했습니다. 비용에 비해 얻는 게 적습니다.

대신 주석의 역할을 좁히는 쪽으로 잡았습니다. 새로 작성하는 주석은 왜 이렇게 했는지만 적고, 무엇을 하는지는 적지 않습니다. 동작 설명은 코드가 바뀌면 틀려지지만, 판단의 이유는 오래 갑니다.

이번에 틀렸던 두 주석이 정확히 동작 설명이었습니다. 하나는 메서드가 무엇을 하는지, 다른 하나는 쿼리가 무엇을 세는지를 적었고 둘 다 코드가 바뀌면서 어긋났습니다.

새 규칙이 얼마나 지켜질지는 지켜봐야 합니다. 지금은 코드 검토에서 동작 설명 주석이 보이면 한 번 묻는 정도로 하고 있습니다. 강제하지는 않습니다. 주석을 안 쓰게 만드는 것보다는 틀린 주석이 낫다고 보기 때문입니다.

오픈소프트랩 개발팀이 작성합니다. 보안 운영 포탈과 생성형 AI 사용 통제를 만들고 있습니다.