package-info.java란

서론

팀 내 코드리뷰를 하다 패키지에 package-info.java 파일이 존재한다는 사실을 알게 되었습니다. package-info.java가 무엇인지 잘 몰랐기에 이번 기회에 알아보고자 합니다.

 

package-info.java란

package-info는 모든 Java 패키지에 추가할 수 있는 Java 파일입니다. package-info.java 파일은 2가지 목적으로 사용됩니다.

• 패키지 단위의 문서 작성
• 패키지 단위의 애노테이션 적용

 

1) 패키지 단위의 문서 작성

JDK5 이전에는 package.html을 통해 패키지 단위의 Javadoc 코멘트를 body 태그 안에 작성했습니다. 그러나 JDK5 이후에는 package-info.java가 등장해 package.html의 역할을 대신하기 시작했습니다. package-info.java의 예시는 다음과 같습니다.

/**
 * 이 클래스는 javadoc의 생성 방법과 예제에 대한 학습 테스트이다.
 * <p>
 * 이 클래스는 javadoc의 애노테이션과 활용 방법에 대해 알아본다.
 * 또한, package-info.java의 생성과 활용 방법에 대해 살펴본다.
 * </p>
 *
 * @since 1.0
 * @author yeongun
 * @version 1.1
 */
package com.example.javadoc;

위의 package-info.java를 패키지 내 생성하면 아래와 같은 Javadoc이 생성됩니다.

 

2) 패키지 단위의 애노테이션 적용

패키지에 공통적인 애노테이션을 적용해야할 때 package-info.java를 활용할 수 있습니다.

 

필드, 파라미터, 반환값이 기본적으로 NotNull인 상황을 예로 들어 봅시다.

이 경우 파라미터나 반환값이 Null이 아니어야 되는 상황에서는 @NonNullApi 애노테이션을, 필드가 Null이 아니어야 되는 상황에서는 @NonNullFields 애노테이션을 package-info.java 파일에 적용하면 됩니다.

@NonNullApi
@NonNullFields
package com.example.javadoc;

import org.springframework.lang.NonNullApi;
import org.springframework.lang.NonNullFields;

보통 파라미터나 반환값이 NotNull이어야 되는 모듈 클래스에 package-info.java를 생성해 @NonNullApi를 적용하는 방식으로 많이 활용합니다.

 

이 외에도 패키지 단위의 애노테이션 적용이 필요한 상황이라면 간단히 package-info.java에 애노테이션을 붙임으로써 문제를 해결할 수 있습니다.

 

package-info.java 파일을 만드는 법

인텔리제이에서 패키지를 오른쪽 클릭한 뒤 New > package-info.java를 클릭해 파일을 생성할 수 있습니다.

 

결론

이 글에서는 package-info.java의 목적과 생성 방법에 대해 살펴봤습니다. package-info.java는 패키지 단위의 문서화나 애노테이션 적용이라는 목적을 갖고 있습니다. 실제로 현업에서는 Javadoc 대신 스웨거나 다른 툴을 이용해 문서화를 하기 때문에 패키지 단위의 공통 애노테이션 적용에 package-info.java를 사용합니다. package-info.java를 사용하면 중복 코드를 손쉽게 제거할 수 있다는 장점이 있기에 적절히 활용하는 것이 좋은 코드습관이라고 생각합니다.

 

참고 문헌

• https://www.baeldung.com/java-package-info
• https://johngrib.github.io/wiki/java/javadoc/