AI가 작성한 코드의 긴 주석은 리뷰 팀에게 독해 뒤의 검증을 요구한다. 개발자 McKayla는 글 Yap: a particular kind of slop에서, 읽는 사람이 이해할 정보를 주지 못한 채 말만 길게 남는 주석을 ‘yap’이라고 부른다. 단순한 타입 정의 위에 30줄짜리 설명이 붙거나, 큰 함수의 내부에는 주석이 거의 없는데 함수 위에만 200줄짜리 서사가 놓인 경우가 여기에 들어간다.
코드는 타입·함수 시그니처·변수 이름을 바꾸면 호출부와 함께 수정해야 한다. 주석은 그렇지 않다. 틀린 채로 시작했거나 변경 뒤에 낡아도 컴파일러가 멈춰 세우지 않는다. 그래서 AI 코드 리뷰에서 주석의 길이는 코드와 분리된 설명을 얼마나 다시 검증해야 하는지 알려 주는 신호가 된다. 줄여야 할 대상은 모든 주석이 아니라 코드가 이미 말하는 일을 반복하거나 현재 동작과 멀어진 주석이다.
왜 긴 주석은 코드보다 먼저 낡는가
주석은 실행 경로에 들어가지 않는다. 주석에는 코드와 다른 관리 규칙이 필요하다. 이름만 읽어도 알 수 있는 동작을 풀어 쓴 문장은 함수가 바뀌는 순간 중복 설명이 되기 쉽다. 반대로 호출 순서, 권한 경계, 데이터 보존처럼 코드 몇 줄만 보고는 알기 어려운 조건은 주석으로 남길 가치가 있다.
McKayla가 지적한 문제도 바로 이 분리다. 저자는 주석을 여러 번 다시 읽고 문장을 덜어 내며 다듬는다고 썼다. AI가 만든 주석은 요구사항을 길게 되풀이하거나 파일 첫머리에 버린 구현의 배경을 쌓기 쉽다. 실제 분기와 가까운 이유는 비워 둔다. 리뷰어가 해야 할 일은 그 글을 더 잘 요약하는 일이 아니라 각 문장이 지금 코드에 필요한지 가르는 일이다.
무엇을 지우고 무엇을 코드 가까이에 남길까
함수 이름과 조건문을 문장으로 다시 읽어 주는 주석은 지운다. if 조건을 자연어로 반복하거나 반환값을 함수 이름 그대로 풀이하는 문장은 코드 수정 때 함께 고쳐야 할 표면만 늘린다. 현재 선택의 이유는 남긴다. 성능, 호환성, 보안, 데이터 복구처럼 대안 중 하나를 택한 이유는 코드만으로 빠지기 쉽고 다음 변경에서 다시 판단해야 할 정보다.
파일 머리에서 오래된 전환 과정을 길게 설명하기보다 그 결정이 영향을 주는 분기·쿼리·예외 처리 바로 옆에 짧게 둔다. 한 문단이 여러 함수와 예외를 한꺼번에 설명하면 어느 문장이 어느 코드와 연결되는지 흐려진다. 설명을 없애지 않고 책임 위치로 되돌리는 편이 리뷰와 유지보수 모두에 낫다.
‘yap’이라는 짧은 말 뒤에 어떤 질문을 붙일까
원문에서 ‘yap’은 네 가지를 다시 묻게 하는 짧은 말이다. 저자는 “이 주석이 어떤 가치를 주는가”, “미래의 독자에게 도움이 되는가”, “이 자리가 맞는가”, “주석이 정말 필요한가”를 다시 생각하라는 줄임말로 쓴다. 팀에서도 긴 지적을 매번 새로 쓰기보다, 이 네 질문을 리뷰 규칙으로 공유할 수 있다.
최종 코멘트는 짧은 낙인보다 코드 위치를 가리켜야 한다. “이 문단은 요구사항을 되풀이한다. 삭제하고 캐시 키가 바뀌는 조건을 invalidate() 호출 옆에 남기자”처럼 말하면 작성자는 무엇을 지우고 무엇을 보강할지 바로 안다. AI에게 다시 수정을 맡길 때도 “주석을 줄여라”보다 “현재 동작과 선택 이유만 남기고, 각 설명을 해당 분기 옆으로 옮겨라”가 더 정확한 작업 지시가 된다.
PR 양식은 설명량 대신 연결을 요구해야 한다
AI가 작성한 PR의 설명란에는 “안전하게 처리했다”, “기존 동작을 유지했다”, “예외를 모두 다뤘다” 같은 문장이 자주 생긴다. 이 문장들은 검토 결과가 아니라 검토할 가설이다. 리뷰 양식에는 긴 배경 설명 대신 네 줄이면 충분하다. 변경 전 동작, 변경 뒤 보장할 동작, 관련 코드 위치, 그 보장을 깨뜨리는 입력을 적게 한다. 각 줄이 테스트 이름이나 함수로 이어지면 리뷰어는 주석의 설득력보다 실제 동작을 먼저 확인할 수 있다.
이 기준은 AI 코드에만 적용되지 않는다. 급한 수정과 오래된 시스템에서도 사람은 설명을 코드보다 먼저 믿기 쉽다. 주석을 줄이는 목적은 다음 독자가 코드만으로 알 수 없는 조건을 더 잘 찾게 하고 승인 근거를 긴 문장에서 관찰 가능한 동작과 테스트로 옮기는 데 있다.
출처: McKayla, Yap: a particular kind of slop (2026-08-29 확인)