9.8.5 문서화 주석(Docstring) 누락 여부 및 파라미터 일치성 검사
“작동하는 코드 자체가 훌륭한 문서다(Code is documentation)“라는 애자일(Agile) 명언은, 모든 코드가 짧고 명료하게 작성된 이상적인 환경에서나 통용되는 말이다. AI가 무한한 속도로 코드를 쏟아내는 환경에서는, 인간 엔지니어가 그 방대한 로직을 일일이 읽고 해석할 시간이 없다. 따라서 AI가 작성한 클래스와 퍼블릭(Public) 메서드에는 반드시 그 의도(Intent)와 용례를 설명하는 **문서화 주석(Docstring)**이 강제되어야 한다.
무문서 코드(Undocumented Code)는 컴파일이 되더라도 유지보수 관점에서는 미완성된 반쪽짜리 납품물이다. 더 나아가, LLM은 종종 코드를 여러 번 반복해서 수정하는 동안 원래 작성해 둔 주석을 업데이트하지 못해, **코드의 실제 파라미터와 주석의 파라미터가 불일치(Mismatch)**하는 심각한 모순(Inconsistency)을 발생시킨다. 이러한 문서적 악취(Documentation Smell)를 추적하는 것 또한 정적 오라클의 임무다.
1. 퍼블릭 API(Public API)에 대한 문서화 강제화
모듈, 클래스, 그리고 외부 패키지에서 호출 가능한 퍼블릭 메서드(Public Method)는 반드시 문서화를 동반해야 한다. 오라클 시스템은 린터(Linter)를 확장하여 이 규칙을 적용한다.
- Python:
pydocstyle혹은flake8-docstrings를 활성화하여,def구문 바로 밑에 삼중 따옴표(""" """)로 감싸진 Docstring이 없는 경우 에러를 발생시킨다. - Java:
Checkstyle의JavadocMethod모듈을 활성화하여 Javadoc 구문(/** ... */)의 존재를 강제한다. - JS/TS:
ESLint의require-jsdoc룰을 통해 퍼블릭 식별자에 대한 JSDoc을 강제한다.
프롬프트 엔지니어링을 아무리 잘하더라도 프롬프트 뒤에서는 결국 휴먼 에러나 모델의 망각이 발생할 수 있다. 오라클이 스니펫에 주석이 부재하다는 에러를 뱉으면, LLM은 *“이 함수에 대한 PEP-257 표준 규격의 Docstring을 포함하여 다시 제출하라”*는 명확한 트리거(Trigger)를 받게 된다.
2. 코드 서명(Signature)과 문서(Documentation) 간의 무결성 검증
가장 골치 아픈 환각(Hallucination)은 주석이 있되 내용이 거짓말인 경우다.
처음 코드를 생성할 때 함수는 compute(amount: float) 였고 주석도 이에 맞게 작성되었다. 이후 수명 주기에서 LLM이 코드 로직을 수정하면서 파라미터를 compute(amount: float, tax_rate: float)로 바꿨음에도, 주석은 예전 상태를 그대로 유지하는 식이다.
이러한 모순을 해결하기 위해 오라클은 AST 파싱 도구(예: Python의 darglint)를 사용하여 실제 함수의 파라미터/리턴 타입과 주석에 명시된 @param, @return 정보 간의 1:1 일치 여부를 검증한다.
- 오라클 워커는 AST에서 정의된 파라미터 이름들의 리스트(
[amount, tax_rate])를 추출한다. - 이후 AST 노드에 매달린 주석 컨텍스트에서 식별자들을 정규식으로 스크래핑(
[@param amount])한다. - 두 집합을 비교(Diff)하여 누락된 설명(
tax_rate에 대한 설명 부재)이 있거나, 실제 코드에는 없는데 주석에만 존재하는 유령 파라미터가 있다면 즉각 빌드를 멈추고 거부(Reject)한다.
3. 의도(Intent) 중심의 문서화 유도
유지보수성 지표 기반 오라클은 형식의 검사에서 머무르지 않고, AI 피드백을 통해 문서를 ’가치 있는 내용’으로 채우도록 훈련시킨다.
단순히 /// @param id user id 와 같은 무의미한 동어반복 주석만 뱉어내는 AI를 제어하기 위해, 고급 오라클은 가벼운 자연어 처리(NLP) 스캐닝을 통해 “주석 내에 ’Why(왜 이 함수가 필요한가)’에 대한 단어가 포함되어 있는가?” 혹은 “주석의 길이가 파라미터 선언부보다 지나치게 짧지 않은가?” 와 같은 휴리스틱(Heuristic) 규칙을 적용할 수 있다.
기계가 작성한 코드를 인간이 안전하게 다루기 위해서는 사용 설명서가 필수적이다. 문서화 일치성 오라클은 코드가 스스로의 한계와 의도를 언어로 증명하지 못하면 샌드박스를 나갈 수 없게 강제함으로써, 엔터프라이즈 시스템이 ’이해할 수 없는 블랙박스(Blackbox)’로 전락하는 현상을 강력히 차단한다.