[java] JSR 305을 활용한 자바 코드 문서화 방법론

29 Nov 2023

java

소개

JSR 305는 자바 언어에서 코드의 의도 및 사용법을 문서화하는 데 도움을 주는 지침을 제공하는 자바 스펙입니다. 이를 활용하면 개발자는 더욱 명확하고 이해하기 쉬운 코드를 작성할 수 있습니다. 이번 글에서는 JSR 305을 활용한 자바 코드 문서화 방법론에 대해 알아보겠습니다.

@Nullable과 @Nonnull 주석

JSR 305에서 제공하는 가장 기본적인 주석은 @Nullable과 @Nonnull입니다. 이 주석들을 사용하면 매개변수, 반환값, 필드 등의 null 가능성을 명시적으로 표현할 수 있습니다. 예를 들어, @Nullable을 사용하면 해당 객체가 null일 수도 있음을 나타내고, @Nonnull을 사용하면 해당 객체가 null이 아님을 나타냅니다.

public void setName(@Nullable String name) {
    this.name = name;
}

@Nonnull
public String getName() {
    return this.name;
}

@ParametersAreNonnullByDefault 주석

@ParametersAreNonnullByDefault 주석은 클래스 레벨에 추가하여, 해당 클래스의 모든 매개변수가 null이 아님을 나타냅니다. 이는 매개변수에 @Nonnull 주석을 명시하지 않아도 자동으로 null이 아님을 가정하도록 도와줍니다.

import javax.annotation.ParametersAreNonnullByDefault;

@ParametersAreNonnullByDefault
public class MyClass {
    // 매개변수에 @Nonnull 주석을 명시하지 않아도 자동으로 null이 아님을 가정한다.
    public void myMethod(String param) {
        // ...
    }
}

@CheckReturnValue 주석

@CheckReturnValue 주석은 메소드의 반환값이 반드시 사용되어야 함을 나타냅니다. 이를 통해 개발자가 메소드의 결과를 무시하지 않도록 유도할 수 있습니다. 예를 들어, Stream 인스턴스에서 filter 메소드를 호출한 후 반환값을 사용하지 않으면 컴파일 경고가 발생합니다.

import javax.annotation.CheckReturnValue;

public class MyClass {
    @CheckReturnValue
    public Stream<Integer> filterOdd(Stream<Integer> numbers) {
        return numbers.filter(n -> n % 2 != 0);
    }
    
    public void exampleUsage() {
        Stream<Integer> numbers = Stream.of(1, 2, 3, 4, 5);
        filterOdd(numbers); // 반환값을 사용하지 않으면 경고 발생
    }
}

결론

JSR 305을 활용하면 자바 코드의 의도 및 사용법을 명확하게 문서화할 수 있습니다. @Nullable과 @Nonnull 주석을 이용하여 null 가능성을 나타내고, @ParametersAreNonnullByDefault 주석으로 매개변수에 대한 가정을 설정할 수 있습니다. 또한, @CheckReturnValue 주석을 사용하여 반환값을 사용하지 않는 경우에 경고를 통해 개발자에게 주의를 줄 수 있습니다.

소개

@Nullable과 @Nonnull 주석

@ParametersAreNonnullByDefault 주석

@CheckReturnValue 주석

결론

참고 자료