Clean Code #4 주석

주석을 최대한 쓰지 말자

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

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
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* \\dd* \\d*);

의도와 중요성을 설명

 

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

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

TODO, FIXME 주석

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

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

 

 

주석보다 annotation

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

-  코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 줄 수 있다. 

@Deprecated: 컴파일러가 warning을 발생시킴. IDE에서 사용시 표시됨

@NotThreadSafe: Thread Safe하지 않음을 나타냄 

 

JavaDoc

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

JavaDoc은 IDE Reader Mode를 사용하면 /,*이 없어지고 설명만 간단하게 볼 수 있어 깔끔해짐

//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
 */
private String heroName;

Method level

/** (JavaDoc은 HTML 문서들로 만들어지기 때문에 문법 사용가능)
 * <p> This is a simple description of the methid. . .
 * <a href="http://www.supermanisthegreatest.com">Superman!</a>
 * </p>
 * @param incomingDamage the amount of incoming damage
   (함수 안에 들어오는 인자에 대한 설명) 
 * @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;
}