4. 주석

소울치킨·2022년 4월 29일
0

클린코드

목록 보기
5/9
post-thumbnail

나쁜 코드에 주석을 달지 마라. 새로 짜라.
브라이언 W. 커니핸, P.J. 플라우거

  • 잘 달린 주석은 어떤 정보보다 유용하다. 그렇지만 코드를 이해하기 어렵게 만들기도 한다. 주석은 '필요악'이다.
    프로그래밍 언어 자체가 표현력이 풍부하다면, 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 필요하지 않다.
    코드로 의도를 표현하지 못해, 실패를 만회하기 위해 주석을 사용한다.
  • 주석은 거짓말을 한다 주석은 오래될수록 코드에서 멀어지고 완전히 그릇된다. 갈수록 코드는 바뀌고 조각난다. 주석은 의미를 잃게된다.

주석은 나쁜 코드를 보완하지 못한다

  • 주석을 추가하는 이유는 코드 품질이 나쁘기 때문이다. 주석을 달지말고 코드를 수정하자.
  • 어지르고 주석으로 덮을 생각말고 난장판을 치우자.

코드로 의도를 표현하라

  • 주석으로 달려는 설명을 함수로 만들어서 표현하자
  • 아래 예시 (직원에게 복지 혜택을 받을 자격이 있는지 검사하기)
// Bad Case
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

// Good Case
if (employee.isEligibleForFullBenefits())

좋은 주석

  • 어떤 주석은 필요하거나 유익하다.

법적인 주석

  • 요구받은 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣는 경우
  • 예) Copyright (C) 2003,......

정보를 제공하는 주석

  • 예) 추상 메서드가 반환할 값을 설명하기
// 테스트 중인 Responder 인스턴스를 반환한다
protected abstract Responder responderInstance();
// 그치만 함수 이름을 responderBeingTested로 바꾸면 주석이 없어도 된다
  • 예) 정규표현식
// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w* \\w* \\d*, \\d*")
// 이왕이면 시각, 날짜를 변환하는 클래스를 만들어 코드를 옮겨주면 더 좋고 깔끔하다. 주석을 없앨 수 있다.

의도를 설명하는 주석

  • 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명하는 주석

의미를 명료하게 밝히는 주석

  • 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
  • 그렇지만 그릇된 주석을 달아놓을 위험이 높다.

결과를 경고하는 주석

  • 더 나은 해결책이 있을 수 있다. 하지만 합리적인 경우가 있다. 효율을 높이기 위함이다.
  • 예) 특정 테스트 케이스를 꺼야하는 이유를 설명하는 주석 // 여유 시간이 충분하지 않다면 실행하지 마세요.

TODO 주석

  • 앞으로 할 일을 //TODO 주석으로 남기면 편하다.
  • 구현하지 않은 이유, 미래의 모습까지 같이 설명해주자.
  • IDE에는 TODO 주석을 찾아주는 기능이 있다. 주기적으로 TODO를 점검해서 없애는 방향으로 가야한다.

나쁜 주석

  • 대다수의 주석.
  • 허술한 코드, 엉성한 코드에 대한 변명. 합리화하려는 주절거리는 독백.

주절거리는 주석

  • 목적없이 의무감으로, 프로세스에서 하라고 하니까 마지못해 주석을 다는 행위

같은 이야기를 반복하는 주석

  • 코드에서 설명한 내용을 설명하는 주석

오해의 여지가 있는 주석

  • 의도는 좋았으나 엄밀하게 주석을 못달게 되면 오해의 여지가 생긴다.
  • 살짝 잘못된 정보로 인해 코드가 잘못되서 고생하게 될 지 모른다.

의무적으로 다는 주석

  • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달지 않는다. 정보를 제공하려는 지나친 욕심이다.
  • 오히려 더 코드가 복잡하게 보인다.

이력을 기록하는 주석

  • 과거에는 깃같은 소스 코드 관리 시스템이 없었지만 이젠 혼란만 가중할 뿐이다.

있으나 마나한 주석

  • 너무 당연한 말은 남기지 않는다.
  • 지나친 참견으로 인해 주석을 무시하는 습관이 생길 수 있다.
  • 함수나 변수로 표현할 수 있다면 주석을 달지않는다.
/**
* 기본 생성자
*/
protected AnnualDateRule() { }

닫는 괄호에 다는 주석

  • 정말 장황하고 중첩되있다면 달아야할 수 있다.
  • 그렇지만 코드를 줄이고 분리할 생각을 하는게 맞다.

주석으로 처리한 코드

  • 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 이유가 있어서 남긴 줄 알게 된다.
  • 소스 코드 관리 시스템을 이용하자. 코드를 잃어버릴 일 없다.

HTML 주석

  • 소스코드가 실행될 HTML 태그부분을 주석으로 보여주지 않는다.

전역 정보

  • 주석으로 달아야한다면 근처에 있는 코드만 기술하기.
  • 시스템 전반적인 정보를 기술하지 않는다.

너무 많은 정보

  • 장황한 정보는 불필요하고 불가사의한 정보일 뿐이다.

모호한 관계

  • 주석이랑 코드가 따로 놀면 안된다.

비공개 코드에서 Javadocs

  • 공개 API에는 Javadocs가 유용하지만 그렇지 않다면 쓸모 없다.
profile
소울치킨입니다

0개의 댓글