메소드 주석을 원하는 템플릿으로 자동 생성할 수 없나?
그래서 방법을 정리해보기로 했다.
기존 사용 방법 (Mac 기준)
1. /** 입력 후 Enter
- IntelliJ IDEA에서는 메소드 위에 /**를 입력하고 Enter를 누르면 기본 JavaDoc 양식이 자동으로 생성된다.
- 하지만 이 방식은 IntelliJ에 기본 내장된 형식을 따르기 때문에, 별도로 설정한 커스텀 템플릿은 적용되지 않는다.
2. Command + Option + Shift + G
- 커스텀 템플릿을 적용하려면 반드시 Command + Option + Shift + G (Generate JavaDoc) 단축키를 사용해야 한다.
- 따라서 이 글에서는 IntelliJ 기본 템플릿 대신, 직접 설정한 템플릿을 적용하는 방법을 소개한다.
JavaDoc 템플릿
아래는 메소드 주석을 자동 생성할 때 사용할 커스텀 JavaDoc 템플릿이다.
/**
* methodName : ${element.getName()}
* description :
<#if element.typeParameters?has_content>
*
</#if>
<#list element.typeParameters as typeParameter>
* @param <${typeParameter.name}> the type parameter
</#list>
<#if element.parameterList.parameters?has_content>
*
</#if>
<#list element.parameterList.parameters as parameter>
* @param ${parameter.name} ${parameter.type?split(":")[1]}
</#list>
<#if isNotVoid>
*
* @return ${element.getReturnTypeElement()?split(":")[1]}
</#if>
<#if element.throwsList.referenceElements?has_content>
*
</#if>
<#list element.throwsList.referenceElements as exception>
* @throws ${exception.referenceName} the ${exceptionNames[exception.referenceName]}
</#list>
*/템플릿 주요 구성 요소
- methodName : 메소드명을 자동으로 삽입한다.
- description : 메소드 설명을 직접 작성할 수 있도록 기본 공간을 마련한다.
- @param : 타입 파라미터와 메소드 파라미터를 각각 자동으로 기입한다.
- @return : 반환 타입이 void가 아닐 경우 반환값에 대한 설명란을 추가한다.
- @throws : 예외가 선언되어 있으면 해당 예외 목록을 자동으로 기입한다.
특별히 주목해야 할 부분
- ${parameter.type?split(":")[1]}
- ${element.getReturnTypeElement()?split(":")[1]}
이 부분을 사용함으로써 불필요한 패키지명이나 기타 정보 없이 타입명만 가져올 수 있다.
IntelliJ IDEA에 템플릿 적용하는 방법
- 설정 열기 File > Settings (Mac은 IntelliJ IDEA > Preferences)
- Tools ➔ JavaDoc ➔ Templates 로 이동
- Methoe level 의 제일 마지막 템플릿을 수정하거나 새로 추가한다.
- 기존 내용을 삭제하고 위의 템플릿을 붙여넣는다.
- 저장 후, 메소드에 커서를 두고 JavaDoc을 생성하는 단축키를 사용한다.
사용 시 주의사항 및 권장사항
- description 항목은 자동 완성되지 않으므로 반드시 메소드 기능을 간결하고 명확하게 작성할 것.
- @param과 @return 설명도 가능하면 의미 있게 채워넣을 것.
- 팀 단위 개발이라면 템플릿을 통일하여 코드 스타일 일관성을 유지할 것.
자동화된 주석 작성 도구를 활용하면 반복 작업을 줄이고, 더 중요한 로직 개발에 집중할 수 있다.
특히 팀 프로젝트나 오랜 시간이 지난 코드의 유지보수를 고려할 때, 잘 작성된 JavaDoc은 매우 큰 도움이 된다.
📚 참고 자료
- IntelliJ IDEA 공식 문서 - Code templates
출처: 사용한 JavaDoc 템플릿은 개인 프로젝트와 여러 오픈소스 프로젝트에서 직접 커스터마이징하여 작성한 버전을 기반으로 함.