[CleanCode] 클린코드 리뷰_ 4장 : 주석

주석을 최대한 쓰지 말자

잘 달린 주석은 그 어떤 정보보다 유용하다.

그러나 경솔하고 근거 없는 주석은 코드를 이해하기 더 어렵게 만든다.

 

프로그래밍 언어 자체가 표현력이 풍부하다면, 

우리에게 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면,

우리에겐 주석이 필요 없을 것이다.

 

즉, 코드에 주석이 달려있다면 코드 품질이 나쁘기 때문일 확률이 높다.

(물론 아닌 경우도 있다. [주석은 이럴때만 쓰자] 에서 알아보자.)

---

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

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

employee.flags , HOURLY_FLAG , employee.age>65 가 모두 true일때 복지혜택을 받을 자격이 있다.

따라서 주석으로 이 코드가 무엇을 체크하는것인지 명시했다.

 

if( employee.isEligibleForFullBenefits() ){}

이 코드를 보자. 위의 사항들을 메서드로 정리했다. 메서드 이름만 보면 이 코드가 무슨 일을 할지 알수있다.

이렇게 의미있는 이름을 지으면 해결된다.

코드로 의도를 표현하라!

자신이 저지른 난장판인 코드를 주석으로 설명하지 말고 개선하는데 시간을 보내야 한다.

---

주석은 방치된다.

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

보통 개발자들이 코드를 수정할 때, 주석을 고려하지 않는다.

따라서 주석은 영구적으로 해당 코드를 설명하지 못한다.

코드가 바뀌면 주석은 아무 쓸모없는 자리만 차지하는 텍스트가 되어버린다.

---

나쁜 주석

이외에도 여러가지 나쁜 주석의 예가 있다.

 

주절거리는 주석 / 같은 이야기를 중복하는 주석 / 오해할 여지가 있는 주석 / 있으나 마나 한 주석

최대한 함수의 이름이나 코드를 명료하게 짜서 주석을 달지 않는게 좋다.

 

의무적으로 다는 주석 / 이력을 기록하는 주석 

기업에서 의무적으로 시켜서 다는건 어쩔 수 없지만, 그래도 안좋은 주석이다.

---

좋은 주석 : 주석은 이럴때만 쓰자

어떤 주석은 필요하거나 유익하다. 

 

그래도 더 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.

---

정보를 제공하는 주석

아래의 정규식 같이 한눈에 들어오지 않지만 써야만 하는 코드를 설명할 때.

즉, 구현에 대한 정보를 제공하는 주석을 사용하는 것은 때때로 좋다.

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

---

의도와 중요성을 설명하는 주석

해당 부분의 코드를 왜 추가했는지 그 의도를 설명하는 주석은 좋다.

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

 

아래는 더 나은 예제이다.

저자가 문제를 해결한 방식에 동의하지 않을지 몰라도, 어쨌거나 저자의 의도는 분명히 드러난다.

// 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도해본다.
for(int i=0;i < 25000; i++){
	WidgetBuilderThread widgetBuilderThread = 
    	new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
	Thread thread = new Thread(widgetBuilderThread);
    thread.start();
}

---

결과를 경고하는 주석

때로는 다른 프로그래머에게 해당 코드의 결과를 경고할 목적으로 주석을 사용한다.

// 여유 시간이 충분하지 않다면 이 테스트케이스는 실행하지 마십시오.
public void _testWithReallyBigFile(){
	//실행시간이 오래걸리는 테스트 코드
}

---

중요성을 강조하는 주석

얼핏 보면 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해 주석을 사용한다.

String listItemContent = match.group(3).trim();
//여기서 trim은 정말 중요하다. trim으로 시작 공백을 제거해줘야 한다.
//문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
new ListItemWidget(this, listItemContent, this.level+1);
return buildList(text.substring(match.end()));

---

TODO , FIXME 주석

//TODO 

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

 

//FIXME

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

 

위의 주석을 남겨두면 IDE에서 하이라이팅 되고, 별도의 윈도우에서 어디부분에 해당 주석을 남겼는지 알 수 있다.

---

주석보다 annotation

애노테이션은 코드에대한 메타 데이터이다.

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

 

@Deprecated

컴파일러가 warning을 발생시킨다. IDE에서 사용 시 표시된다.

---

@NotThreadSafe

Thread Safe하지 않음을 나타낸다.

@NotThreadSafe
public void deleteItem(HashMap<String,Integer> map, String item){
}

---

JavaDoc

JavaDoc 주석은 주석 공간을 열때 /뒤에 *두개를 붙여서 사용한다.

이렇게 하면, Java 코드에서 API문서를 HTML 형식으로 생성해준다.

---

Class level , Field level , Method level

각각의 level마다 JavaDoc 작성 방법이 조금 씩 다르다.

여기서 다루지는 않겠지만, JavaDoc에 대해서는 따로 공부해보길 바란다.