4장. 주석

오늘 읽은 범위

• 4장. 주석

기억하고 싶은 내용

• “나쁜 코드에 주석을 달지 마라. 새로 짜라.” (p.68)
• 주석은 나쁜 코드를 보완하지 못한다. (p.69)
  • 코드 품질이 나쁘다면 주석을 추가할 것이 아니라 코드를 정리해야 한다.
• 코드로 의도를 표현하라! (p.70)
• 좋은 주석 (p.70)
  • 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.
  • 법적인 주석
  • 정보를 제공하는 주석: 주석이 유용하다 할지라도, 가능하다면, 함수 이름에 정보를 담는 편이 더 좋다.
  • 의미를 명료하게 밝히는 주석: 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
  • 결과를 경고하는 주석: 때로 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.
  • TODO 주석
  • 중요성을 강조하는 주석
  • 공개 API에서 Javadocs: Javadocs 역시 독자를 오도하거나, 잘못 위치하거나, 그럿된 정보를 전달할 가능성이 존재한다.
• 나쁜 주석 (p.75)
  • 대다수 주석이 이 범주에 속한다.
  • 주절거리는 주석
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석: 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 다아야 한다는 규칙은 어리석기 그지없다.
  • 이력을 기록하는 주석: 소스 코드 관리 시스템이 있으므로 혼란만 가중할 뿐이다.
  • 있으나 마나 한 주석
  • 무서운 잡음: 때로는 Javadocs도 잡음이다.
  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라.
  • 위치를 표시하는 주석
  • 닫는 괄호에 다는 주석
  • 공로를 돌리거나 저자를 표시하는 주석: 소스 코드 관리 시스템에 저장하는 편이 좋다.
  • 주석으로 처리한 코드: 이제는 주석으로 처리할 필요가 없다. 그냥 코드를 삭제하라.
  • HTML 주석
  • 전역 정보: 주석을 달아야 한다면 근처에 있는 코드만 기술하라.
  • 너무 많은 정보
  • 모호한 관계: 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
  • 함수 헤더: 짧은 함수는 긴 설명이 필요 없다.
  • 비공개 코드에서 Javadocs

소감 및 생각

• 코드에 주석을 상세하게 많이 달수록 좋은 코드라고 생각했던 시기가 있었다. 지금 생각해보면 코드로 명확하게 설명하지 못했었기 때문에 주석으로 설명하려고 했던 것 같다. 대부분의 설명은 코드를 잘 짠다면 해결이 될 것이고, 정말 꼭 필요한 곳에서만 제한적으로 주석을 달아야 할 것이다.
• 레거시 코드를 파악하면서 업데이트되지 않은 잘못된 주석에 낚였던 적이 여러번 있었다. 그러다 보니 지금은 주석을 무시하는 편이다. 오히려 주석때문에 파악이 더 어려워지는 결과가 되었다. 그래서 불필요하다고 생각되면 주석을 과감하게 제거하는 편이다. 만약 기존 주석을 살려야 한다며 이전 커밋로그를 보면 되니까.