[클린 코드: Clean Code] 4장 주석

클린 코드를 읽고 있습니다

오늘은 4장 주석입니다

오늘도 코드 리팩토링을 하면서 몇년 간 쌓인 주석들과 주석화된 코드를 보며 암담했습니다

---

 

나쁜 코드에 주석을 달지 마라. 새로 짜라.

- 브라이언 W. 커니핸, P.J. 플라우거

 

잘 달린 주석은 그 어떤 정보보다 유용하지만 오래되고 잘못 작성된 주석은 잘못된 정보를 퍼뜨린다

주석은 기껏해야 '필요악' 이다

주석은 오래될수록 코드에서 멀어진다, 언제나 코드를 따라가지 못한다.

부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.

 

그럼 어떻게 해야하나?

주석보다 코드를 떠 잘 쓰려는 방안으로 가라

 

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

표현력이 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다

주석으로 설명하는 대신 코드를 깨끗하게 하는 데 시간을 보내라

 

코드로 의도를 표현하라!

확실히 코드만으로 의도를 설명하기 어려운 경우가 존재한다

하지만 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다

 

좋은 주석

저자는 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라 했다

 

법적인 주석

- 저작권 정보, 소유권 정보 등 법적 이유를 가진 주석

 

정보를 제공하는 주석

- 기본적인 정보를 주석으로 제공하면 편리

- ex) 함수 역할

 

의도를 설명하는 주석

- 때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다

 

의미를 명료하게 밝히는 주석

- 인수나 반환값 자체를 명확하게 (이해가능 하게) 만들면 좋겠지만 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다

assertTrue(a.compareTo(a) == 0);	// a == a

 

결과를 경고하는 주석

- 예를 들어 테스트케이스에서 시간이 오래 걸리는 테스트가 있다면 특정 테스트 케이스를 꺼야 하는 이유를 설명하는 주석을 작성할 수 있다

 

TODO 주석

- '앞으로 할 일'을 // TODO 주석으로 남기면 편리하다. 주기적으로 정리하는 것이 좋다

 

중요성을 강조하는 주석

공개 API에서 Javadocs

- Javadocs는 Java 소스를 문서화할 수 있는 툴이다

- 공개 API를 구현한다면 다른 사람들이 사용할 수 있도록 Javadocs를 열심히 작성하는 것이 좋다

 

나쁜 주석

주절거리는 주석

- 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다

같은 이야기를 중복하는 주석

- 주석이 같은 코드 내용을 그대로 중복한 경우다. 이런 경우 코드보다 주석을 읽는 시간이 더 오래 걸릴 수 있다

오해할 여지가 있는 주석

의무적으로 다는 주석

- 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석다.

- 아래와 같은 주석은 아무 가치도 없다. 오히려 코드를 헷갈리게 만들며, 거짓말할 가능성을 높인다

/**
* @param title CD 제목
* @param author CD 저자
* @param tracks CD 트랙 숫자
*/
public void addCD(String title, String author, int tracks) {
	CD cd = new CD();
    cd.title = title;
    cd.author = author;
    cd.tracks = tracks;
    cdList.add(cd);
}

 

이력을 기록하는 주석

- 지금은 소스 코드 관리 시스템이 있으니 이력을 기록하는 주석은 없애자

있으나 마나 한 주석

- 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석

/**
*	기본 생성자
*/
protected AnnualDateRule() {
}


/* 월 중 일자  */
private int dayOfMonth;

 

주석으로 처리한 코드 (중요한 거라 bold)

- 주석으로 처리된 코드는 사람들이 지우기를 주저한다. 점차 주석화된 코드가 쌓인다

- 소스 코드 관리 시스템이 우리를 대신해 기억해준다. 지워도 된다. 지우자

 

너무 많은 정보

- 필요한 정보만 제공하자

---

오늘은 주석에 대한 내용을 보았다

주석이야 말로 코드 스타일에서 가장 갈리는 주제가 아닐까 싶다. 주석을 써야 하느냐 말아야하느냐, 무엇이 좋은 주석이냐 등등

나는 주석은 있어야 한다고 생각한다. 결국 나한테 도움이 되니까. 그런데 위에서 나온 내용처럼 단순한 정보랄지, 함수 등으로 표현할 수 있는 것들은 주석으로 작성하는 것을 지양해야 한다

특히 마지막에 나온 '주석으로 처리한 코드'야말로 코드를 지저분하게 만드는 데 일조하는 녀석이다

언젠간 쓰겠지, 이유가 있어서 했겠지 라는 생각으로 코드의 발전을 막는다.

 

주석을 잘 쓰는 것도 연습이지만 그 전에 코드를 잘 작성하면 주석도 꼭 필요한 것만 작성할 수 있게된다!!