2024 08 08 TIL : Javadoc과 주석달기

나는 지금까지 주석이라고는 그냥  //(메서드가 하는 일) 정도로만 달고있었는데, Javadoc 문서화 주석이라는 걸 알게됐다. 내가 짠 코드를 나중에 다시 볼 때나, 다른 사람들이 내 코드를 볼 때 확실히 보기 좋은 것 같아서 정리해보려고 한다. 

 

Javadoc 주석이란? 

Javadoc 주석은 '/** ... */' 형식으로 작성되며, 주로 클래스, 메서드, 필드 등에 대한 설명을 작성하는데 사용된다. 주석 내부에 특정 태그를 사용하면 문서화 할 때 유용한 정보를 포함할 수 있다. 가장 많이 사용되는 태그 중 하나가 '@param' 태그다.

 

주요 Javadoc 태그 

@param : 메서드의 매개변수(parameter)를 설명한다.

@return  : 메서드의 반환값을 설명한다.

@throws (또는 @exception) : 메서드가 던질 수 있는 예외를 설명한다. 

@deprecated : 더 이상 사용되지 않는 메서드나 클래스에 대해 설명한다. 

@see : 관련된 다른 클래스나 메서드에 대한 참조를 제공한다. 

 

예시

/**
*두 정수를 더하는 메서드
*
*@param a 첫 번째 정수
*@param b 두 번째 정수
*@return 두 정수의 합 int
*/
public int add(int a, int b) {
	return a + b;
    }

 

왜 Javadoc 주석을 사용하는가? 

그냥 '//두 정수를 더하는 메서드' 이렇게 적고 매개변수, 리턴값도 그냥 메서드 선언한 것만 보면 알 거 같은데 왜 굳이 이렇게 적는가싶었지만, 나중에 더 로직이 더 복잡해지고, 메서드의 수도 많아지면, 설명돼있는 걸 보는 게 훨씬 가독성이 좋은 이유도 있고, 다른 이유도 있다

 

1. 자동 문서 생성 : Javadoc 툴을 사용하면 코드에서 바로 API 문서를 생성할 수 있어, 코드와 문서의 일관성을 유지하기 쉽다.

2. 유지보수 용이 : 코드와 주석이 함께 관리되기 떄문에, 코드 변경 시 문서도 자동으로 업데이트 된다. 

 

그럼 여기서 말하는 api 문서는 어떤 걸 말하는 걸까? 

자바 소스 코드에 Javadoc 주석을 달앋두면, Javadoc 툴을 사용해 주석을 바탕으로 HTML 형식의 문서를 자동으로 생성할 수 있다는 뜻이다. 이 문서는 API에 대한 상세한 설명을 포함하며, 개발자가 작성한 클래스, 메서드, 필드 등에 대한 설명을 포함한다. 이렇게 생성된 문서는 자바 API의 사용법을 이해하고, 다른 개발자들이 해당 코드를 참고할 때 사용할 수 있는 중요한 자료가 된다. 

 

인텔리제이에서는 아주 간편하게 Javadoc을 만들 수 있다 . 

 

 

이렇게 만들어진 Javadoc에서 index.html을 들어가보면 

 

 

주석으로 적었던 정보들이 들어있는 걸 확인할 수 있다. 앞으로는 Javadoc 주석을 활용해서 더 가독성 좋은 코드를 만드려고 해봐야겠다.