클린코드 - 4.주석

나쁜 코드에 주석을 달지 마라. 새로 짜라
- 브라이언 w. 커니핸, P.J.플라우거

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

코드를 작성하고 보니 짜임새가 엉망이고 알아보기 어렵다면 주석이 아니라 코드를 다시 정리해야 한다

주석으로 설명하기보다는 깔끔하고 정돈된 코드가 훨씬 보기 좋다

---

2. 코드로 의도를 표현하라!

코드만으로 의도를 설명하기 어려운 경우 메서드를 분리하여 표현할 수 있다

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

if (employee.isEligibleForFullBenefits()) {
...
}

---

3. 좋은 주석

• 법적인 주석
  • 저작권 정보, 소유권 정보 등
• 정보를 제공하는 주석
  • but, 함수 이름에 표현하는 것이 더 바람직함
• 의도를 설명하는 주석

// 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도한다.
for (int i=0; i<25000; i++) {
...
}

• 의미를 명료하게 밝히는 주석
  • 인수나 반환값을 명확하게 만들면 좋겠지만, 표준 라이브러리 등 변경하지 못하는 코드에 속할 경우 유용하다
  • 더 나은방법이 있는지 고민하고 어쩔 수 없이 주석을 사용해야 할 경우 그릇된 주석이 되지 않도록 각별히 주의해야한다
• 결과를 경고하는 주석
  • 시간이 오래걸리는 테스트 코드 등에 경고 (ex. 실행 시간이 굉장히 오래 걸림)
  • 하지만 Junit을 사용한다면 @Ignore("실행 시간이 굉장히 오래 걸림") 을 사용하자
• TODO 주석
• 중요성을 강조하는 주석
• 공개 API에서 Javadocs

---

4. 나쁜 주석

나머지 대다수의 주석들이며, 코드에 대한 변명일 뿐이다

주석은 가독성을 해치며, 있으나 마나 하거나 같은 말을(코드로 표현됨) 반복할 뿐이다

또한 오해의 소지가 있을 수 있다 (코드가 변경되거나 했을 경우 놓치기도 쉬움)

 

주석은 최대한 쓰지말자

---

마무리 느낀 점

평소에 주석을 많이 달려고 노력하는 편이었다

그게 팀원들을 위한 일이라고 생각했고,

유지보수하기 더 좋은 작업이라고 생각했다

이번 글을 읽어보니 주석으로 내 코드를 변명하고 있었다는 느낌이 든다...ㅜ

주석을 사용하지 않기 위해서는 앞에서 읽었던 내용인

네이밍 작업과 정확한 단위 메서드로 표현하는 부분에 더 많은 신경을 쏟아야 될 것 같다