클린 코드, 4. 주석

클린 코드, 4. 주석

코드만이 정확한 정보를 제공하는 유일한 출처다. 주석은 잘못된 정보를 전달하기 쉽다. 주석을 가능한 줄이도록 노력해야 한다.

• 주석은 나쁜 코드를 보완하지 못한다.
  표현력이 풍부하고 깔끔하며 주석이 없는 코드가 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
• 코드로 의도를 표현하라.
  주석으로 의도를 전달하기 보다는 코드로 표현하려 노력하자.
• 좋은 주석
  • 법적인 주석
    저작권 정보 또는 소유권 정보, 계약조건 등
  • 정보를 제공하는 주석
    눈으로 보기엔 이해하기 힘든 메서드의 반환값을 설명해주는 주석, 그러나 함수 이름을 바꾸거나 다른 클래스를 만들어 코드를 이동하면 주석을 달지 않아도 되는 경우가 많다.
  • 의도를 설명하는 주석
    어떤 구현 방법 결정에 대한 의도를 설명하는 주석
  • 의미를 명료하게 밝히는 주석
    ex) assertThat(a.compareTo(a) == 0); // a == a
    그릇된 주석을 다는 것은 매우 위험하므로 다른 방법이 없을 때만 사용하고 정확히 달도록 주의해야 한다.
  • 결과를 경고하는 주석
    특정 테스트 케이스 실행을 권고하거나(JUnit의 @ignore로 대체가능) 객체 생성에 있어서 주의점을 경고하는 등
  • TODO 주석
    구현이나 수정이 필요하지만 당장은 구현하기 어려운 업무를 기술한다. 없애도 괜찮을 때는 빨리 없애기.
  • 중요성을 강조하는 주석
    대수롭게 여겨질 수 있는 코드의 중요성을 강조할때 사용한다.
  • 공개 API에서 Javadocs
• 나쁜 주석
  대다수의 주석
  • 주절거리는 주석
    보는 사람이 이해하지 못하도록 제대로 소통하지 않는 주석
  • 같은 이야기를 중복하는 주석
    코드 내용만으로도 충분이 전달되는 내용을 한번 더 적은 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
    모든 멤버에 Javadocs를 추가하는 등
  • 이력을 기록하는 주석
    대신 소스 관리 시스템을 사용하자
  • 있으나 마나 한 주석
    너무나도 당연한 사실이나 정보를 주는 주석
  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라
  • 위치를 표시하는 주석 (배너)
  • 공로를 돌리거나 저자를 표시하는 주석
    소스 관리 시스템을 사용하자
  • 주석으로 처리한 코드
    코드를 기억하기 위해 주석 처리한 코드, 소스 관리 시스템을 사용하자
  • HTML 주석
  • 전역 정보
    주석 근처의 코드에 대해서만 기술하자. 통제도 할수 없고 유지보수도 힘들다.
  • 너무 많은 정보
    흥미로운 역사나 관련없는 정보
  • 모호한 관계
    주석과 주석이 설명하는 코드 사이에 관계가 명백해야 한다.
  • 함수 헤더
  • 비공개 코드에서 Javadocs