CleanCode(클린코드) - 4장. 주석

January 28, 2022

🔖 오늘 읽은 범위 : 4장

😃 책에서 기억하고 싶은 내용을 써보세요.

주석은 오래될수록 코드에서 멀어진다. (p.68)
나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다. (p.69)
주석은 나쁜 코드를 보완하지 못한다. (p.69)
코드로 의도를 표현하라! (p.70)

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

위 코드보다 아래와 같이 주석으로 달려는 서렴ㅇ을 함수로 만들어 표현해도 충분하다.
if (employee.isEligibleForFullBenefits())

좋은 주석
- 법적인 주석 : 저작권 정보, 소유권 정보
- 정보를 제공하는 주석
- 의도를 설명하는 주석
- 의미를 명료하게 밝히는 주석
  - 때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다. 일반적으로는 인수나 반환값 자체를 명확하게 만들면 좋겠지만, 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
- 결과를 경고하는 주석
  - 특정 테스트 케이스를 꺼야 하는 이유를 설명하는 주석이 있다.
- TODO 주석
  - 앞으로 할 일을 // TODO 주석으로 남겨두면 편하다.
  - 더 이상 필요 없는 기능을 삭제하라는 알림, 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등에 유용하다.
  - 주기적으로 TODO 주석을 점검해 없애도 괜찮은 주석은 없애라고 권한다.
- 중요성을 강조하는 주석
- 공개 API 에서 Javadocs
나쁜 주석
- 주절거리는 주석
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석
- 의무적으로 다는 주석
- 이력을 기록하는 주석
  - 사람들은 모듈을 편집할 때마다 모듈 첫머리에 주석을 추가한다.
  - 모듈 첫머리 주석은 지금까지 모듈에 가한 변경을 모두 기록하는 일정의 일지 혹은 로그가 된다. (p. 80)
- 있으나 마나 한 주석
- 무서운 잡음
- 함수나 변수로 표현할 수 있다면 주석을 달지 마라
```
// 전역 목록 <smodule> 에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))

이 코드에서 주석을 없애고 다시 표현하면 아래와 같다.
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubsystem))
```
- 위치를 표시하는 주석
- 닫는 괄호에 다는 주석
- 공로를 돌리거나 저자를 표시하는 주석
- 주석으로 처리한 코드
- HTML 주석
- 전역 정보
  - 주석을 달아야 한다면 근처에 있는 코드만 기술하라. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.
- 너무 많은 정보
- 모호한 관계
- 함수 헤더
- 비공개 코드에서 Javadocs
  - 공개 API 는 Javadocs 가 유용하지만 공개하지 않을 코드라면 Javadocs 는 쓸모가 없다.

🤔 오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

최대한 주석을 작성하지 않으려고 노력하지만, 가끔 내가 잘못 작성한 코드를 보고 이해가 안될 때 주석을 작성하고 싶어진다. 그래도 항상 참고 주석을 작성하지 않고 코드를 변경하려고 노력하는데 이 부분은 잘해왔다고 생각한다.

앞으로 클린 코드에 있는 정보를 기반으로 코드 리뷰 할 때에도 주석이 있으면 주석보다는 코드로 표현해보자고 얘기해봐야겠다.

🔥 소감 3줄 요약

코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.
주석은 나쁜 코드를 보완하지 못한다.
좋은 주석은 법적인 주석, 정보, 의도, 결과를 경고하는 주석, TODO 주석이 있다.

Written by@sujin-park

항상 배우는 자세 갖추기 💻

GitHub LinkedIn

← CleanCode(클린코드) - 3장. 함수