[CleanCode] 4장 주석

agpine12·어제
0

🧹  CleanCode

목록 보기
4/4
post-thumbnail

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

  • 잘 달린 주석은 그 어떤 정보보다 유용하다.

  • 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.

  • 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨린다.

  • 사실 주석은 필요악 이다. 프로그래밍 언어의 표현력을 높힌다면 주석은 필요없다.

  • 우리는 의도를 표현하지 못한, 실패를 만회하기 위해 주석을 작성한다.

  • 주석은 언제나 실패를 의미한다.

  • 코드로 의도를 표현 할때 마다 스스로를 칭찬해준다.

주석을 달때마다 표현력이 없다는 것을 푸념해라.

  • 애초에 주석이 필요없는 방향으로 코드를 작성해라.
  • 진실은 언제나 코드에만 존재한다.

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

주석을 추가하는 일반적인 이유는, 코드의 품질이 나쁘기 때문이다.
주석을 정리한다? (X) → 코드를 정리한다! (O)

코드로 의도를 표현하라!

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

// TOBE
if (employee.isEligibleForFullBenefit())

좋은주석

안쓰는게 최선이나 유익한 주석이 있다.

‣ 법적인 주석

  • 소스파일 첫머리의 저작권/ 소유권 과 같은 계약조건 법적인 정보. (IDE에서 주석 헤더를 자동으로 축소해줌)

‣ 정보를 제공하는 주석

// 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();
  • 반환값을 명시 ⇒ 함수명으로 표현하는것 추천 ex. responderBeingTested
// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");
  • 정규표현식에 대한 설명 ⇒ 시각과 날짜를 변환하는 클래스로 추출하는 것 추천.

‣ 의도를 설명하는 주석

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

‣ 결과를 경고하는 주석

‣ TODO 주석

‣ 중요성을 강조하는 주석

‣ 공개 API에서 Javadocs

나쁜 주석

‣ 주절거리는 주석

‣ 같은 이야기를 중복하는 주석

‣ 오해할 여지가 있는 주석

‣ 의무적으로 다는 주석

‣ 이력을 기록하는 주석

‣ 있으나 마나 한 주석

‣ 무서운 잡음

‣ 함수나 변수로 표현할 수 있다면 주석을 달지 마라

‣ 닫는 괄호에 다는 주석

‣ 공로를 돌리거나 저자를 표시하는 주석

‣ 주석으로 처리한 코드

‣ HTML 주석

‣ 전역정보

‣ 너무 많은 정보

‣ 모호한 관계

‣ 함수 헤더

‣ 비공개 코드에서 Javadocs

‣ 예제

profile
Later never comes 👩🏻‍💻

0개의 댓글