4장 - 주석

개요

• 주석은 잘달리면 유용하다.

• 쓸데없는 주석이나 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.

• 주석을 쓴다는 것은 내가 코드를 잘 설명한다는것에 실패했다는 의미.

• 왜냐면 그것을 보완하는 설명을 주석으로 쓰는것이니까.

• 주석은 오래될수록 코드랑 멀어진다. 오래될수록 완전히 잘못될 가능성도 높아진다.

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

• 주석 달아도 코드 그지같은건 그지같은거니까 코드 그지같은거나 고쳐라

1. 코드로 의도를 표현하라.

• 주석으로 달려는 설명도 코드로 충분히 표현할수 있다.

1. 좋은 주석

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

• 하지만 정말 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석이란것을.

• 법적인 주석

  • 회사가 정립한 구현 표준에 맞춰 특정 주석을 넣으라고 명시한다.
  • 이럴 경우 사용한다.
  • 그리고 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고도 타당하다.
  • ( 쓰레기라더니 좋게말함 ㅋㅋ)

• 정보를 제공하는 주석

  • 추상 메서드가 반환할 값을 설명할 경우
    • 하지만 가능하다면 함수 이름에 정보를 담자.
  • 정규표현식이 시각과 날짜를 뜻하는 경우를 주석으로 표현할때
  • 이럴 경우는 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮겨주면 더 깔끔해지고
  • 주석이 필요 없어진다.

• 의도를 설명하는 주석

  • 때떄로 주석은 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.

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

  • 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
  • 그릇된 주석을 달 확률도 높아진다.
  • 그래서 주석을 검증하기가 쉽지가 않으므로 고민하고 사용하도록 한다.

• 결과를 경고하는 주석

  • 테스트케이스를 실행하면 안될 경우 사용하는 주석

  • 이럴떈 @Ignore 애노테이션을 사용 하자. 예) @Ignore("시간이 오래걸리니까 쓰지마세요")

  • //쓰레드에 안전하지 못하다.

  • //그래서 각 인스턴스를 독립적으로 생성해야 된다.

  • 위와 같은 주석이 아주 합리적이다.

  • 쓰레드를 정적으로 초기화 시켜서 사용할수도 있는데 이 주석을 보고 실수를 면한다.

• Todo 주석

  • 때로는 앞으로 할일을 주석으로 남겨두면 편하다.
  • 함수를 구현하지 않은 이유와 미래 모습을 Todo 주석으로 설명할수 있다.
  • 당장 필요하지도 않고 구현하기가 쉽지 않은 것들을 써논다.
  • 하지만 TOdo 코드로 떡칠하는건 좋지 않다.
  • 주기적으로 Todo 주석을 점검해 없애도 괜찮은 주석은 없애자.

• 중요성을 강조하는 주석

  • 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해 주석을 사용한다.
  • ( 이건 나쁘다 좋다 별말이 없다 )

• 공개 API에서 javadocs

  • 설명이 잘 된 공개 API는 참으로 유용하고 만족스럽다.
  • 특히 표준 자바 라이브러리에서 사용한 javadocs가 좋은 예다.
  • 공개 API를 구현한다면 javadocs를 아주 잘써야된다.

1. 나쁜주석

• 대다수 주석이 이 범주에 속한다.

• 쓸데없이 주절거리는 주석

  • 자기만 이해하는 주석은 낭비다.

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

  • 알기쉬운 코드를 그대로 주석으로 옮겨논것
  • 간단하거나 다 아는것들을 쓸데없이 여러번 쓰는것
  • 이건 예제를 봐야됨. 목록 4-2 ContainerBase.java

• 오해할 여지가 있는 주석

  • 오해할 여지조차 주게 하면 안된다.

• 의무적으로 다는 주석

  • 모든 함수에 javadocs를 넣으라는 규칙 같은건 하면 안된다.

• 이력을 기록하는 주석

  • 이젠 git같은 소스관리 시스템같은게 있으니까 그만달자.

• 있으나 마나 한 주석

  • 이런건 쓰지말자.
  • 예) 기본생성자

• 무서운 잡음

  • 변수명과 동일한 주석
  • ( 진짜 똑같음 )

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

• 위치를 표시하는 주석

  • 가독성이 구려지므로 특히 뒷부분에 슬래쉬 ex ) //////// 이런식으로 끝나는 잡음은 제거하는 편이 좋다.
  • 진짜 필요할떄만 아주 드물게 사용해라

• 닫는 괄호에 다는 주석

  • } // try
  • 위처럼 닫는 괄호에 주석 다는대신 함수를 줄이려고 시도해라.

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

  • 이제 git과 같은 소스코드 관리시스템이 있으므로 지워라

• 주석으로 처리한 코드

  • 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다.
  • 그냥 지워라.
  • git이 기억해준다.

• HTML 주석

  • 혐오 그자체다
  • 도구로 주석을 뽑아 웹페이지에 올릴 작정이라면 그건 도구가 해야할일이다.

• 전역정보

  • 주석을 달아야 한다면 근처에 있는 코드만 써라
  • 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 쓰지마라.
  • 왜냐면 시스템 어딘가에 있는것들을 설명한것인데 그것이 어딨는지 읽는사람은 전혀 모르니까.

• 너무 많은 정보

  • 주석에다 흥미로운 역사나 관련 없는 정보를 쓰지마라.

• 모호한 관계

  • 주석과 주석이 설명하는 코드는 둘사이의 관계가 명백해야 한다.
  • 주석자체가 다시 설명을 요구해선 안된다.

• 함수 헤더

  • 짧은 함수는 긴 설명이 필요없다.
  • 함수를 짧고 한가지만 수행하도록 만들며 함수에 이름 잘붙여라 함수헤더같은거 쓰지말고

• 비공개 코드에서 javadocs

  • 공개하지 않을거면 쓸모가 없다.