[클린코드] 주석

1. 주석을 최대한 쓰지 말자
2. 좋은 주석
3. 주석보다 annotation
4. JavaDoc

 

주석을 최대한 쓰지 말자

• 주석은 나쁜 코드를 보완하지 못한다.

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if((employee.flags & HOURLY_FLAG) && employee.age > 65))

// 의미있는 이름을 지으면 해결된다.
if (employee.isEligibleForFullBenefits())

주석으로 설명하지 말고 개선하는데 시간을 보내야 한다.

코드로 의도를 표현할 수 있어야 한다.

 

• 주석은 방치된다.

코드의 변화에 따라가지 못하고, 주석은 방치된다.

코드는 컴파일되어 호출되지만, 주석은 그저 주석이기 때문에 그 자리에 방치되고 의미없는 텍스트가 되어버린다.

 

좋은 주석

• 구현에 대한 정보를 제공한다.

// kk:mm:ss EEE, MMM dd, yyyy 형식

Pattern timeFormat = Pattern.compile("\\d*:\\d:\\d* \\w*, \\w* \\d* \\d*");

 

• 의도와 중요성을 설명한다.

// 스레드를 많이 생성하여 시스템에 영향을 끼쳐 테스트를 만들도록 함
for (int i = 0; i < 25000; i++) {
    SomeThread someThread = ThreadBuilder.builder().build();
}

// 유저로부터 입력받을 값을 저장할 때 trim으로 공백제거 필요
String userName = userNameInput.trim();

 

• TODO, FIXME 주석

// TODO : 앞으로 할일, 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둘 때.

// FIXME : 문제가 있지만, 당장 수정할 필요는 없을 때, 가능하면 빨리 수정하는게 좋다.

IDE에서 하이라이팅되고, 별도의 윈도우에서 볼 수 있다.

 

주석보다 annotation

• java.lang.annotation
  • annotation = 코드에 대한 메타 데이터
  • 코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 줄 수 있다.
• @Deprecated : 컴파일러가 warning을 발생시킴, IDE에서 사용시 표시됨
• @NotThreadSafe : Thread Safe하지 않음을 나타냄 (책에서는 주석으로 표현했지만 어노테이션을 많이 사용)

 

JavaDoc

Java 코드에서 API 문서를 HTML 형식으로 생성해주는 도구

// This is a single line comment

/*
 * This is a regular multi-line comment
 */

/**
 * This is a Javadoc
 */

 

• Class level

/**
 * Please see the {@link com.baeldung.javadoc.Person} class for true identity
 * @author choi
 * 
 */
public class Jiseok extends Person {
    // fields and methods
}

IDE 에서는 @link 어노테이션을 사용하면 해당 클래스를 인식한다.

 

• Field level

/**
 * The public name of a celebrity that is common knowledge
 */
private String celebrityName;

 

• Method level

/**
 * <p>This is a simple description of the method...
 * <a href="https://chjs93.tistory.com/">Welcome!</a>
 * </p>
 * @param readPages is amount of books read
 * @return the amount of study
 * @see <a herf="https://github.com/jiseok-choi">github</a>
 * @since 1.0
 */
public int successfullyStudy(int readPages) {
    // do something
    return 0;
}

javadoc 은 html 로 이루어져 있기 때문에 p, a 태그 등을 사용할 수 있다.

@param 파라미터 설명

@return 리턴 설명

@see 참고 정보

@since

Javadoc 의 장점으로는 IDE Reader Mode 를 사용하여 설명 위주로 코드를 볼 수도 있다.