목차

1. 주석

2. 좋은 주석

3. 나쁜 주석

1. 주석

  • 필요악으로 표현
  • 코드로 의도를 표현하지 못해, 실패를 만회하기 위해 주석을 사용함
  • 주석이 필요한 상황에 처하면 곰곰히 생각할 것
  • 현실적으로 코드와 주석을 모두 유지보수하는 것은 어렵기 때문에 주석에 대한 좋은 인식이 없음

  • 코드로 의도를 표현해라

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

 // 후
 if (employee.isEligibleForFullBenefits())

2. 좋은 주석

  • 법적인 주석
    • 각 소스 파일 첫머리에 추가한 표준 주석 헤더
  • 정보를 제공하는 주석
    • 기본적은 정보를 제공함 ex) 추상 메서드가 반환할 값을 설명
  • 의도를 설명하는 주석
    • 때때로 주석은 결정에 깔린 의도까지 설명함
  • 의미를 명료하게 밝히는 주석
    • 때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워짐
  • 결과를 경고하는 주석
    • 프로그래머에게 경고를 할 목적으로 사용하는 주석
  • TODO 주석
    • 앞으로 할 일을 남기는 주석
  • 중요성을 강조하는 주석
    • 자칫 대수롭지 않다고 여겨질 무언가의 중요성을 강조하기 위해서 주석을 사용

2. 나쁜 주석

  • 주절거리는 주석
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
  • 이력을 기록하는 주석
  • 있으나 마나 한 주석
  • 위치를 표시하는 주석
  • 닫는 괄호에 다는 주석
  • 공로를 돌리거나 저자를 표시하는 주석
  • 주석으로 처리한 코드
  • HTML 주석
    • pre tag나 기타 html 태그를 사용
    • 필자도 한때 pre를 사용해서 indentation을 적용해본 기억이 있음
  • 전역 정보
  • 너무 많은 정보
  • 모호한 관계
  • 함수 헤더