[Java] JavaDoc 란 무엇일까 ?

javadoc 란 ?

 

• Javadoc은 JDK와 함께 패키지로 제공되는 도구 입니다. JDK가 설치 되어있다면 Javadoc을 사용할 수 있으며, Java 소스 코드의 코드 문서를 생성하는데 도움을 주는 도구
• 위에 설명하는것처럼 문서를 생성하는데 도움을 주는 도구이다. 내가 생각하고 사용한건 해당 메서드나 클래스가 어떤 일을 하는지 간단하게 설명해주는 주석느낌이다.

/**
     * Save a vehicle.
     *
     * @param vehicle the entity to save.
     * @param file the file to store the entity.
     * @return the persisted entity.
     */
    Vehicle create(Vehicle vehicle, MultipartFile file) throws IOException;

// 내가 사용한 javadoc 파람값, 리턴값 등 필요한 데이터를 정리해놓았다.

• javadoc 의 목적을 목표는 특정 코드 덩어리의 대략적인 역할을 3초 안에 파악할 수 있도록 도와주는 것이다. 라고 한다.

/**
     * 팀 기체 조회
     * @param teamId
     * @return 해당 team의 소유인 기체 리스트를 리턴합니다.
     */
    @Override
    public List<Vehicle> getTeamVehicles(Long teamId) {
        List<Vehicle> vehicles = vehicleRepository.findVehiclesByTeamId(teamId);
        return vehicles;
    }

// 블로그에서는 가독성이 가장 중요하다고 했다. 나는 영어를 잘 못하기때문에 한글로 작성한 경우도 많다!

또한 블로그에서는 javadoc 작성 원칙을 다음과 같이 정의한다.

• 가독성이 가장 중요하다.
• 특정 메소드나 클래스의 "책임"을 3초 안에 파악할 수 있도록 짧고 간결하게 적는다.
• 메소드 Javadoc에 대해
  • 메소드가 무엇을 입력받아서 무엇을 리턴하는지를 반드시 설명한다.
  • 뭐가 리턴되는지만 알아도 레거시 코드 파악에 큰 도움이 된다. (Golang에서 배운 것)
  • 메소드가 어떤 경우에 어떤 예외를 던지는지를 케이스별로 설명한다.
  • 구현에 대해서는 설명하지 않는다. 구현이 바뀌면 주석도 바뀌게 된다. (구현과 주석이 커플링이 생기지 않도록 한다.)
• 클래스 Javadoc이라면, 이 클래스의 책임 또는 목표가 무엇인지를 설명한다.
• 주석은 메소드 시그니처와 클래스 시그니처 위에만 Javadoc 포맷으로 작성하고, 그 외의 주석은 가능한 한 작성하지 않는다.

리턴값을 반드시 설명한다.

• 처음 보는 메소드가 아무리 복잡하더라도 무엇을 받아서 무엇을 리턴하는지만 알려준다면, 그 메소드를 사용해야 하는 사람의 시간을 굉장히 절약해줄 수 있다고한다.
• 블로그는 코드를 예시로 설명한다.

// 싫음: 리턴값이 무엇인지를 설명하지 않는다.
/**
 * 문자열이 문자들의 시퀀스 s를 포함하는지 확인합니다.
 */
public boolean contains(CharSequence s) {

// 좋음: 무엇을 리턴하는지 명확히 표현한다.
/**
 * 문자열이 문자들의 시퀀스 s를 포함한다면 true를 리턴하고, 그렇지 않다면 false를 리턴합니다.
 */
public boolean contains(CharSequence s) {

• 위 코드와 같이 리턴값은 명확하게 설명하도록 하자.

예외 클래스라면 어떤 경우에 던지는지 설명한다.

// 좋음: Task를 못 찾으면 이 예외를 throw 하면 된다고 알려준다.
/**
 * 할 일을 찾지 못했을 때 던집니다.
 */
public class TaskNotFoundException extends RuntimeException {

// 싫음
/**
 * 할 일을 찾지 못했을 때 발생하는 예외입니다.
 */
public class TaskNotFoundException extends RuntimeException {

구현에 의존하지 않는다.

• 구현 코드에 의존하는 javadoc은 코드와 커플링이 생겨 좋지 않다고 생각한다고한다.

// 싫음: 지금은 루프를 돌지만, 다른 방식으로 구현이 바뀌면 주석은 거짓이 된다.
/**
 * 문자열의 앞부터 루프를 돌면서 문자열이 문자들의 시퀀스 s를 포함하는지 확인합니다.
 */
public boolean contains(CharSequence s) {

// 좋음: 구현이 바뀌어도 사실을 말하는 주석.
/**
 * 문자열이 문자들의 시퀀스 s를 포함하는지 확인합니다.
 */
public boolean contains(CharSequence s) {

• 메소드의 책임과 역할만 짧게 설명하는 것이 좋다고한다.

 
이와 같이 잘 정리된 주석은 코드를 파악하는데 훨씬 효율적이며 시간을 많이 들이지 않아도 괜찮은것같다.