8장 주석 자제하기

주석을 자제해야 하는 이유

1. 코드를 더 명확히 하는 것이 좋다. 타입명과 변수명을 명확하게 사용하면 된다
2. 주석은 컴파일러가 확인하지 않으므로 코드가 수정된 후에 주석이 맞다고 보장할 수 없다
3. 코드가 복잡해보인다

이해할 수 없는 코드를 주석으로 해결하지 마라

해결책

오래된 주석 제거

• 오래된 주석
  • 이제 관련 없거나 정확하지 않음
  • 읽는데 시간만 낭비한다
  • 잘못된 방향으로 코드를 짤 수 있음

주석 처리된 코드

• 주석 처리된 코드는 모두 삭제해야 한다
• git을 사용하자

불필요한 주석 제거

• 코드가 주석만큼 읽기 쉬울 때 해당 주석을 불필요한 주석이라고 한다.
• 예

  // 에러 로그
  Logger.error(errorMessage, e);

메서드의 이름으로 주석 대신하기

• 코드를 문서화하는 경우
  • 주석으로 코드를 설명하지 말고 메서드로 추출해라

불변속성을 문서화한 주석 유지

• 불변속성을 주석으로 설명한 경우
  • ‘이 주석으로 누군가 버그를 만드는 것을 막을 수 있는가?’
  • 주석 대신 코드로 만들 수 없는지 점검해야 한다
• 컴파일러나 테스트로 불변속성을 검증할 수 없다면 주석을 유지한다
  • 예: 테스트나 시물레이션하기 어려운 경우 주석으로 표현한다
• 프로세스의 불변속성
  • todo, fixme 같은 주석은 남겨도 된다
  • 하지만 실제로 수정하거나 구현해야 한다. 주석 표시된 작업을 미루지 말고 제거하기 위해 노력해야 한다