코드를 보조하는 주석

클린 코드 북스터디

목록 보기

3/13

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

주석을 최대한 쓰지 말자

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

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

주석은 방치된다.

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

02. 좋은 주석

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

//kk:mm:ss EEE, MMM dd, yyyy 형식
Pattern timeFormat = 
	pattern.complie("\\d*:\\d:\\d* \\w*, \\w* \\d* \\d*);

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

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

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

TODO, FIXME 주석

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

03. 주석보다 annotation

java.lang.annotation

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

@Deprecated : 컴파일러가 warning을 발생시킴. IDE에서 사용 시 표시됨
@NotThreadSafe : Thread Safe 하지 않음을 나타냄 (책에서는 주석으로 표현했지만 어노테이션을 많이 사용)

04. JavaDoc

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

Class Level

/**
 * Hero is the main entity we'll be using to ...
 *
 * Please see th {@link com.baeldung.javadoc.Person} class for true  identity 
 * @author catain 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

/**
 * <p>This is a simple description of th method...
 * <a href="http://www.supermanisthegreatest.com">SuperMan!</a>
 * </p>
 * @parma 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;
}