김주엽

1. 📌 핵심 개념 정리

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

주석은 나쁜 코드를 보완하지 못한다
- 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
- 표현력이 풍부하고 깔끔하고 주석이 거의 없는 코드가 주석이 많은 코드보다 훨씬 좋다.
- 주석으로 설명할 시간에 코드를 깔끔하게 수정하자.

코드로 의도를 표현하라!
코드만으로 의도를 설명하기 어려운 경우가 존재한다.
많은 개발자가 이를 코드는 훌륭한 수단이 아니라고 의미로 해석한다. 그러나 이는 잘못된 생각이다.
- 개선 전
```
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags && HOURLY_FLAG) && (employee.age > 65))
```
- 개선 후
```
if (employee.isEligibleForFullBenefits())
```
함수 이름을 통해 주석 없이도 의미를 표현할 수 있게 개선됐다.

좋은 주석
- 법적인 주석: 회사가 정립한 구현 표준에 맞춰 법적인 주석을 명시하는 것은 필요한 주석이다.
- 정보를 제공하는 주석: 때로는 기본적인 정보를 주석으로 제공하면 편리하다.
  하지만 가능하면 함수 이름에 정보를 담자.
- 의도를 설명하는 주석: compareTo 메서드와 같이 비교하는 함수가 있을 때 어떤 기준으로 우선 순위를 정하는지 주석으로 작성하면 도움이 된다.
- 결과를 경고하는 주석: 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용하라.
- TODO 주석: 때로는 앞으로 할 일을 주석으로 남겨두면 편리하다.

나쁜 주석
대다수의 주석이 이 범주에 속한다.
허술한 코드를 지탱하거나 엉성한 코드를 변명하거나 미숙한 결정을 합리화해서 주석으로 남긴다.
- 주절거리는 주석: 이해가 안 되어 다른 모듈까지 찾아야 하는 주석은 바이트만 낭비할 뿐이다.
- 같은 이야기를 중복하는 주석: 이런 주석들은 실제 코드보다 부정확해 독자가 함수를 대충 이해하고 넘어가게 만든다.
- 의무적으로 다는 주석: 모든 함수 혹은 변수에 Javadocs를 달거나 주석을 다는 규칙은 코드를 복잡하게 만든다.
- 있으나 마나 한 주석: 너무나 당연한 정보를 담는 주석을 피하라.
  - 예시: // 기본 생성자, 월 중 일자를 반환한다., 숫자를 저장
- 위치를 표시하는 주석: 소스 파일에서 특정 위치를 표시하려 주석을 사용하는 것은 피해라.
  - 예시: // Actions ////////////////////
- 닫는 괄호에 다는 주석: 닫는 괄호에 주석을 달기 전에 함수를 줄이려 시도해라.
- 주석으로 처리한 코드: 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다.
  - 이는 결국 쓸모 없는 코드가 점차 쌓여가는 것을 볼 수 있다.
  - 요즘은 소스 코드 관리 시스템(Git)이 대신 코드를 기억하니 깔끔하게 주석을 지워라.

책을 읽으며 이해하기 어려웠던 개념이나 명확하지 않았던 내용을 정리합니다.

코드로 의도를 표현하라!
- 어려웠던 부분
  가능하면 주석 대신 함수 이름으로 표현하라는 저자의 의견을 동의하기 어려웠다.
- 궁금한 점
  많은 개발자가 함수 이름을 짓는 데 많은 시간을 들이는데 주석까지 신경 쓰면 코드 작성 시간이 더 늘어나는 것은 아닐까?

코드로 의도를 표현하라
- 주제
  주석 대신 코드로 의견을 표현하는 것이 오히려 더 어려운 방법은 아닐까?
- 설명
  대다수의 개발자가 이름 짓기에 많은 시간을 투자하는데 여기에 주석까지 신경 쓰면 코딩 부담이 더욱 커지는 행동이 아닐까?