[Clean Code] Comments

도모·2023년 3월 13일

Clean Code

목록 보기

3/5

정리한 내용 중 잘못된 내용이 있을 수 있습니다. 잘못된 내용이 있다면 꼭 알려주세요.

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

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

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

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

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

주석은 방치된다.

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

2.좋은 주석

구현에 대한 정보 제공

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

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

TODT, FIXME 주석

TODO: 앞으로 할 일, 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둘 때
FIXME: 문제가 있지만, 당장 수정할 필요는 없을 때. 가능하면 빨리 수정하는게 좋다.

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

3.주석보다 annotation

annotation이란?

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

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

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

4.JavaDoc

JavaDoc이란?

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

// This is a single line comment

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

JavaDoc을 어떻게 사용하는지 각각의 Level 관점으로

1.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 Captaion America
 *
 */
public class SuperHero extends Person {
	// fields and methods
}

2.Field Level

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

3.Method Level

/**
 * <p>This is a simple description of the method ...
 * <a href="http://www.supermanisthegreatest.com">Spuerman!</a>
 * </p>
 * @param incommingDamage the amount of incomming 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 incommingDamage) {
	// do something
	return 0;
}