문서화 드리프트 문제점
개발 과정에서 메서드 시그니처가 변경되거나 반환 타입이 달라져도 @param, @return 태그가 업데이트되지 않는 ‘문서화 드리프트’가 흔히 발생합니다. 이는 새로운 예외가 발생해도 @raise 태그가 누락되거나 매개변수 이름이 바뀌어도 문서가 따라가지 못하는 상황으로 이어집니다. 이러한 문제점은 나중에 코드를 다시 볼 때 메서드의 실제 동작을 파악하는 데 불필요한 시간을 소모하게 만들며, 최근 LLM 기반의 코딩 워크플로우에서는 문서 품질이 AI 어시스턴트의 유용성에 직접적인 영향을 미쳐 잘못된 문서가 LLM 성공률을 절반으로 떨어뜨릴 수 있음이 확인되었습니다.
YARD-Lint의 주요 기능
YARD-Lint는 다음과 같은 다양한 문서화 문제를 감지합니다:
-
문서화 드리프트: 문서화되어야 할 클래스, 모듈, 메서드, 매개변수 중 문서화되지 않은 항목을 찾아냅니다.
-
타입 정확성: @param, @return, @option 태그 내의 유효하지 않은 Ruby 클래스 타입 정의를 식별합니다.
-
누락된 컨텍스트: 옵션 매개변수에 @option 태그가 없거나, 물음표 메서드(예:
empty?)에 반환 타입 문서화가 없는 경우를 감지합니다. -
깨진 예제: @example 태그 내의 Ruby 구문 오류를 찾아냅니다.
-
의미론적 문제: @abstract 메서드에 실제 구현이 있거나 태그 순서가 일관적이지 않은 경우를 확인합니다.
-
YARD 파서 오류: 알 수 없는 태그, 유효하지 않은 지시문, 중복 매개변수, 잘못된 형식의 구문 등을 감지합니다.
사용 방법 및 점진적 도입
YARD-Lint는 RuboCop과 유사한 방식으로 설치 및 설정됩니다. Gemfile에 gem 'yard-lint'를 추가한 후 bundle exec yard-lint --init으로 초기 설정 파일을 생성하고, bundle exec yard-lint app/와 같이 프로젝트에서 실행할 수 있습니다. .yard-lint.yml 파일을 통해 모든 유효성 검사기(validator)를 제어하고, 특정 검사를 활성화/비활성화하거나 심각도 수준을 조정하고, 파일별로 제외 규칙을 설정할 수 있습니다.
특히 YARD-Lint는 점진적 도입을 강력하게 지원합니다. --diff main 옵션을 사용하여 변경된 파일만 린팅하거나, --staged 옵션으로 커밋 전 스테이징된 파일만 검사하여 레거시 코드베이스에도 부담 없이 적용할 수 있습니다. 또한, 특정 유효성 검사기를 새로운 코드에만 적용하거나 (Include 옵션), 레거시 코드를 제외하는 (Exclude 옵션) 방식으로 점진적으로 문서화 품질을 개선해 나갈 수 있습니다.