3. 코드를 보조하는 주석

in 클린코드 on Clean-code



코드를 보조하는 주석


1. 주석을 최대한 쓰지 말자

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

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


// 의미있는 이름을 지으면 해결된다. 👍
if (employee.isEligibleForFullBenefits())
  • 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
  • 자신이 저지른 난장판을 주석으로 설명하지 말고 개선하는데 시간을 보내야 한다
  • 코드로도 의도를 표현할 수 있다.


주석은 방치된다.

  • 코드의 변화에 따라가지 못하고, 주석은 방치된다.
  • 코드는 컴파일되어 호출되지만, 주석은 그저 주석이기 때문에 그 자리에 방치되고 결국 의미없는 텍스트가 되어버린다.
  • 위의 코드에서 ‘복지 혜택에 연금 혜택 기준이 추가된다면?’



2. 좋은 주석

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

// 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 = TreadBiulder.builder().build();
}

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


TODO, FIXME 주석

  • TODO : 앞으로 할 일. 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둘 때.
  • FIXME : 문제가 있지만, 당장 수정할 필요는 없을 때. 가능하면 빨리 수정하는게 좋다.
  • IDE 에서 하이라이팅되고, 별도의 윈도우에서 볼 수 있다.



3. 주석보다 annotation

java.lang.annotation

annotation = 코드에 대한 메타 데이터

  • 코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 줄 수 있다
  • @Deprecated : 컴파일러가 warning을 발생시킴. IDE에서 사용시 표시됨
  • @NotThreadSafe : Thread Safe하지 않음을 나타냄



4. JavaDoc

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

// This is a single line comment

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


Class level

/**
  * hero is the main entity we'll be using to...
  *
  * Please see the {@link com.baeldung.javadoc.Person} class for true identity
  * @author Captain America
  *
  */
  public class SuperHero extends Person {
    // fields and methods
  }


Field level

/**
  * The public name of a hero that is common knowledge
  */
  public String heroName;


Method level

/**
  * <p> This is a simple description of the method...
  * <a href="http://www.supermanisthegreates.com"Superman!</a>
  * </p>
  * @param incomingDamage the amount of incoming incomingDamage* @return the amount of health hero has after attack
  * @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
  * @since 1.0
  */
  public int successfullyAttacked(int incomingDamage) {
    // do something
    return 0;
  }


JavaDoc 사용시 좋은점

  • IDE Reader Mode 를 통해 깔끔하고 직관적인 문서화 가능
  • 나의 코드에 대한 요구사항, 기능 등을 작성해주면 좋음