[Java] javadoc이란 | 전제조건 & 사후조건 @param, @return @throw

javadoc 이란?

javadoc은 자바 개발자들이 자바 소스 코드를 문서화하기 위해 사용하는 도구입니다. javadoc은 소스 코드에 있는 특정 주석을 기반으로 문서를 생성합니다. 이러한 문서에는 소스 코드에 대한 명세서(specification), 클래스(class)와 메서드(method)의 사용 방법, 인수(parameter)와 반환 값(return)의 의미 등의 정보가 포함됩니다.

Fig. 1. javadoc 예시

 

왜 작성해야하죠?

javadoc을 사용하면 다른 개발자들이 소스 코드를 이해하고 사용하는 데 도움이 되는 자세한 문서를 제공할 수 있습니다. 또한 javadoc을 사용하면 코드에 변경이 있을 때 문서를 업데이트하거나 새로 생성할 수 있으므로 소스 코드와 일관성 있는 문서를 유지할 수 있습니다.

 

꼭 개발에 관련된 부분이 아니더라도 우리는 시간을 줄일려는 노력을 많이합니다. 결국에 어떤 것을 진행할때, 시간적으로 들어가는 비용또한 상당하기 때문이죠, javadoc 도 마찬가지입니다. 어떤 개발자가 코드를 건네받아서 수정해야하는데, 코드를 해석하는데 많은 시간을 투자한다면 비효율적이기 때문입니다.

 

Behavioral Equivalence(행동적 동등성)

javadoc을 배우면서 파생되는 행동적 동등성이라는 개념이 있습니다.

행동적 동등성(behavioral equivalence)은 두 개의 시스템이 동일한 방식으로 작동하는지 확인하는 개념입니다. 쉽게 말해서, 두 시스템이 외부에서 보았을 때 같은 행동을 하는 것으로 간주되면, 그 두 시스템은 행동적으로 동등하다고 할 수 있습니다. 다음과 같은 코드는 행동적으로 동등할까요?

static int findFirst(int[] arr, int val){
	for(int i=0; i<arr.length; i++){
		if(arr[i] == val) return i;
    }
        return -1;
}
static int findLast(int[] arr, int val) {
    for (int i = arr.length - 1; i >= 0; i--) {
        if (arr[i] == val) return i;
    }
       	return arr.length;
}

결론적으로 행동적으로 동등하지 않습니다. 두 함수는 다른 목적을 가지고 있으며, 서로 다른 결과를 반환하기 때문입니다.

• findFirst 함수는 주어진 배열 arr에서 val 값이 처음으로 나타나는 인덱스를 찾습니다. 만약 val 값이 배열에 없으면, -1을 반환합니다.
  
  
• findLast 함수는 주어진 배열 arr에서 val 값이 마지막으로 나타나는 인덱스를 찾습니다. 만약 val 값이 배열에 없으면, arr.length를 반환합니다.

두 함수는 배열 내에서 val 값을 찾는 방법과 반환값이 다르므로, 동일한 입력에 대해 서로 다른 출력을 생성합니다. 이 때문에 이 두 함수는 행동적으로 동등하지 않습니다. 

 

 

javadoc 과 행동적 동등성의 상관관계

javadoc 과 같은 정확한 명세가 존재할 때, 기존 구현을 다른 구현으로 대체하는 것이 가능해지며, 이를 통해 효율성이나 시간 단축을 도모할 수 있습니다. 새로운 시스템이 기존 시스템과 같은 입력값에 대해 동일한 결과를 도출할 때, 두 시스템은 행동적으로 동등하다고 할 수 있습니다. 이렇게 함으로써, 소프트웨어 개발자들은 시스템 변경 시 올바른 작동을 보장할 수 있습니다.

---

 

전제조건(Precondition)& 사후조건(Postcondition)

메서드의 명세는 두 가지 절로 구성됩니다:

1. 전제조건(precondition): 'requires' 키워드로 표시됩니다. 전제조건은 클라이언트(즉, 메서드를 호출하는 쪽)에게 부여되는 의무입니다. 이것은 메서드가 호출되는 상태에 대한 조건입니다. 
2. 사후조건(postcondition): 'effects' 키워드로 표시됩니다. 사후조건은 메서드를 구현하는 개발자에게 부여되는 의무입니다.

Fig. 2. 전제조건 & 사후조건 명세

간단히 말하면, 전제조건은 메서드 호출 전에 충족되어야 하는 조건이고, 사후조건은 메서드 호출 후에 충족되어야 하는 결과를 설명합니다. 이를 통해 클라이언트와 구현자 사이에 명확한 의사소통이 가능해지며, 소프트웨어의 품질과 안정성이 향상됩니다.

 

자바의 전제조건 & 사후조건

이 내용을 설명하기 위해 앞에 전제조건과 사후조건을 설명했는데, Java는 문서화 주석에 대한 규칙을 가지고 있습니다. 이 규칙에서는 매개변수가 @param 절로 설명되고, 결과는 @return 및 @throws 절로 설명됩니다.

1. 가능한 전제조건을 @param에 넣습니다.
   - @param 절은 메서드의 매개변수에 대한 설명을 제공합니다. 전제조건은 메서드가 호출되기 전에 충족되어야 하는 조건이므로, 매개변수와 관련된 전제조건은 @param 절에 작성해야 합니다.
2. 사후조건을 @return 및 @throws에 넣습니다.
   - @return 절은 메서드가 반환하는 결과에 대한 설명을 제공합니다. 사후조건은 메서드 호출 후 충족되어야 하는 결과를 설명하므로, 반환값과 관련된 사후조건은 @return 절에 작성해야 합니다.
   - @throws 절은 메서드에서 발생할 수 있는 예외에 대한 설명을 제공합니다. 예외와 관련된 사후조건은 @throws 절에 작성해야 합니다.

이러한 방식으로 Java에서는 문서화 주석을 사용하여 메서드의 전제조건과 사후조건을 표현하며, 이를 통해 클라이언트와 구현자 사이의 계약을 명확하게 정의할 수 있습니다.

 

2023.03.24 - [자바 JAVA] - [Java] 블랙 박스 테스트 & 화이트 박스 테스트 & 커버리지(Coverage) 예시

[Java] 블랙 박스 테스트 & 화이트 박스 테스트 & 커버리지(Coverage) 예시

---